# fiftyone.core.stages
View stages.
Copyright 2017-2026, Voxel51, Inc.
[voxel51.com](https://voxel51.com/)
**Classes:**
| [`ViewStage`](#fiftyone.core.stages.ViewStage)() | Abstract base class for all view stages. |
|-------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`Concat`](#fiftyone.core.stages.Concat)(samples) | Concatenates the contents of the given [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to this collection. |
| [`Exclude`](#fiftyone.core.stages.Exclude)(sample_ids) | Excludes the samples with the given IDs from a collection. |
| [`ExcludeBy`](#fiftyone.core.stages.ExcludeBy)(field, values) | Excludes the samples with the given field values from a collection. |
| [`ExcludeFields`](#fiftyone.core.stages.ExcludeFields)([field_names, meta_filter, ...]) | Excludes the fields with the given names from the samples in a collection. |
| [`ExcludeFrames`](#fiftyone.core.stages.ExcludeFrames)(frame_ids[, omit_empty]) | Excludes the frames with the given IDs from a video collection. |
| [`ExcludeGroups`](#fiftyone.core.stages.ExcludeGroups)(group_ids[, ordered]) | Excludes the groups with the given IDs from a grouped collection. |
| [`ExcludeLabels`](#fiftyone.core.stages.ExcludeLabels)([labels, ids, instance_ids, ...]) | Excludes the specified labels from a collection. |
| [`Exists`](#fiftyone.core.stages.Exists)(field[, bool]) | Returns a view containing the samples in a collection that have (or do not have) a non-`None` value for the given field or embedded field. |
| [`FilterField`](#fiftyone.core.stages.FilterField)(field, filter[, only_matches, ...]) | Filters the values of a given field or embedded field of each sample in a collection. |
| [`FilterLabels`](#fiftyone.core.stages.FilterLabels)(field, filter[, only_matches, ...]) | Filters the [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) field of each sample in a collection. |
| [`FilterKeypoints`](#fiftyone.core.stages.FilterKeypoints)(field[, filter, labels, ...]) | Filters the individual [`fiftyone.core.labels.Keypoint.points`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoint.points) elements in the specified keypoints field of each sample in the collection. |
| [`GeoNear`](#fiftyone.core.stages.GeoNear)(point[, location_field, ...]) | Sorts the samples in a collection by their proximity to a specified geolocation. |
| [`GeoWithin`](#fiftyone.core.stages.GeoWithin)(boundary[, location_field, ...]) | Filters the samples in a collection to only match samples whose geolocation is within a specified boundary. |
| [`GroupBy`](#fiftyone.core.stages.GroupBy)(field_or_expr[, order_by, reverse, ...]) | Creates a view that groups the samples in a collection by a specified field or expression. |
| [`Flatten`](#fiftyone.core.stages.Flatten)([stages]) | Returns a flattened view that contains all samples in a dynamic grouped collection. |
| [`Limit`](#fiftyone.core.stages.Limit)(limit) | Creates a view with at most the given number of samples. |
| [`LimitLabels`](#fiftyone.core.stages.LimitLabels)(field, limit) | Limits the number of [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) instances in the specified labels list field of each sample in a collection. |
| [`MapLabels`](#fiftyone.core.stages.MapLabels)(field, map) | Maps the `label` values of a [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) field to new values for each sample in a collection. |
| [`MapValues`](#fiftyone.core.stages.MapValues)(field, map) | Maps the values in the given field to new values for each sample in a collection. |
| [`SetField`](#fiftyone.core.stages.SetField)(field, expr[, \_allow_missing, ...]) | Sets a field or embedded field on each sample in a collection by evaluating the given expression. |
| [`Match`](#fiftyone.core.stages.Match)(filter) | Filters the samples in the collection by the given filter. |
| [`SelectGroupSlices`](#fiftyone.core.stages.SelectGroupSlices)([slices, media_type, ...]) | Selects the specified group slice(s) from a grouped collection. |
| [`ExcludeGroupSlices`](#fiftyone.core.stages.ExcludeGroupSlices)([slices, media_type]) | Excludes the specified group slice(s) from a grouped collection. |
| [`MatchFrames`](#fiftyone.core.stages.MatchFrames)(filter[, omit_empty]) | Filters the frames in a video collection by the given filter. |
| [`MatchLabels`](#fiftyone.core.stages.MatchLabels)([labels, ids, instance_ids, ...]) | Selects the samples from a collection that contain (or do not contain) at least one label that matches the specified criteria. |
| [`MatchTags`](#fiftyone.core.stages.MatchTags)(tags[, bool, all]) | Returns a view containing the samples in the collection that have or don't have any/all of the given tag(s). |
| [`Mongo`](#fiftyone.core.stages.Mongo)(pipeline[, \_needs_frames, \_group_slices]) | A view stage defined by a raw MongoDB aggregation pipeline. |
| [`Select`](#fiftyone.core.stages.Select)(sample_ids[, ordered]) | Selects the samples with the given IDs from a collection. |
| [`SelectBy`](#fiftyone.core.stages.SelectBy)(field, values[, ordered]) | Selects the samples with the given field values from a collection. |
| [`SelectFields`](#fiftyone.core.stages.SelectFields)([field_names, meta_filter, ...]) | Selects only the fields with the given names from the samples in the collection. |
| [`SelectFrames`](#fiftyone.core.stages.SelectFrames)(frame_ids[, omit_empty]) | Selects the frames with the given IDs from a video collection. |
| [`SelectGroups`](#fiftyone.core.stages.SelectGroups)(group_ids[, ordered]) | Selects the groups with the given IDs from a grouped collection. |
| [`SelectLabels`](#fiftyone.core.stages.SelectLabels)([labels, ids, instance_ids, ...]) | Selects only the specified labels from a collection. |
| [`Shuffle`](#fiftyone.core.stages.Shuffle)([seed, \_randint]) | Randomly shuffles the samples in a collection. |
| [`Skip`](#fiftyone.core.stages.Skip)(skip) | Omits the given number of samples from the head of a collection. |
| [`SortBy`](#fiftyone.core.stages.SortBy)(field_or_expr[, reverse, create_index]) | Sorts the samples in a collection by the given field(s) or expression(s). |
| [`SortBySimilarity`](#fiftyone.core.stages.SortBySimilarity)(query[, k, reverse, ...]) | Sorts a collection by similarity to a specified query. |
| [`Take`](#fiftyone.core.stages.Take)(size[, seed, \_randint]) | Randomly samples the given number of samples from a collection. |
| [`ToPatches`](#fiftyone.core.stages.ToPatches)(field[, config, \_state]) | Creates a view that contains one sample per object patch in the specified field of a collection. |
| [`ToEvaluationPatches`](#fiftyone.core.stages.ToEvaluationPatches)(eval_key[, config, \_state]) | Creates a view based on the results of the evaluation with the given key that contains one sample for each true positive, false positive, and false negative example in the collection, respectively. |
| [`ToClips`](#fiftyone.core.stages.ToClips)(field_or_expr[, config, \_state]) | Creates a view that contains one sample per clip defined by the given field or expression in a video collection. |
| [`ToTrajectories`](#fiftyone.core.stages.ToTrajectories)(field[, config, \_state]) | Creates a view that contains one clip for each unique object trajectory defined by their `(label, index)` in a frame-level field of a video collection. |
| [`ToFrames`](#fiftyone.core.stages.ToFrames)([config, \_state]) | Creates a view that contains one sample per frame in a video collection. |
**Exceptions:**
| [`ViewStageError`](#fiftyone.core.stages.ViewStageError) | An error raised when a problem with a [`ViewStage`](#fiftyone.core.stages.ViewStage) is encountered. |
|------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
### *class* fiftyone.core.stages.ViewStage
Bases: `object`
Abstract base class for all view stages.
[`ViewStage`](#fiftyone.core.stages.ViewStage) instances represent logical operations to apply to
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) instances, which may
decide what subset of samples in the collection should pass though the
stage, and also what subset of the contents of each
[`fiftyone.core.sample.Sample`](fiftyone.core.sample.md#fiftyone.core.sample.Sample) should be passed. The output of
view stages are represented by a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView).
**Attributes:**
| [`has_view`](#fiftyone.core.stages.ViewStage.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.ViewStage.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.ViewStage.to_mongo). |
|------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`outputs_dynamic_groups`](#fiftyone.core.stages.ViewStage.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
| [`flattens_groups`](#fiftyone.core.stages.ViewStage.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
**Methods:**
| [`get_edited_fields`](#fiftyone.core.stages.ViewStage.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
|-----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_filtered_fields`](#fiftyone.core.stages.ViewStage.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_selected_fields`](#fiftyone.core.stages.ViewStage.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.ViewStage.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_media_type`](#fiftyone.core.stages.ViewStage.get_media_type)(sample_collection) | 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. |
| [`get_group_expr`](#fiftyone.core.stages.ViewStage.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.ViewStage.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`load_view`](#fiftyone.core.stages.ViewStage.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
| [`to_mongo`](#fiftyone.core.stages.ViewStage.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
| [`validate`](#fiftyone.core.stages.ViewStage.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.ViewStage.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.ViewStage.to_mongo).
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.ViewStage.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ViewStage.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ViewStage.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
### *exception* fiftyone.core.stages.ViewStageError
Bases: `Exception`
An error raised when a problem with a [`ViewStage`](#fiftyone.core.stages.ViewStage) is encountered.
**Methods:**
| [`add_note`](#fiftyone.core.stages.ViewStageError.add_note)(object, /) | Exception.add_note(note) -- add a note to the exception |
|------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
| [`with_traceback`](#fiftyone.core.stages.ViewStageError.with_traceback)(object, /) | Exception.with_traceback(tb) -- set self._\_traceback_\_ to tb and return self. |
**Attributes:**
| [`args`](#fiftyone.core.stages.ViewStageError.args) | |
|-------------------------------------------------------|----|
#### add_note(object,)
Exception.add_note(note) –
add a note to the exception
#### args
#### with_traceback(object,)
Exception.with_traceback(tb) –
set self._\_traceback_\_ to tb and return self.
### *class* fiftyone.core.stages.Concat(samples)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Concatenates the contents of the given
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to this collection.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
#
# Concatenate two views
#
view1 = dataset.match(F("uniqueness") < 0.2)
view2 = dataset.match(F("uniqueness") > 0.7)
stage = fo.Concat(view2)
view = view1.add_stage(stage)
print(view1)
print(view2)
print(view)
#
# Concatenate two patches views
#
gt_objects = dataset.to_patches("ground_truth")
patches1 = gt_objects[:50]
patches2 = gt_objects[-50:]
stage = fo.Concat(patches2)
patches = patches1.add_stage(stage)
print(patches1)
print(patches2)
print(patches)
```
* **Parameters:**
**samples** – a [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) whose
contents to append to this collection
**Attributes:**
| [`samples`](#fiftyone.core.stages.Concat.samples) | The [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) whose contents to append to this collection. |
|---------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`flattens_groups`](#fiftyone.core.stages.Concat.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.Concat.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.Concat.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.Concat.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.Concat.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.Concat.to_mongo)(_) | Returns the MongoDB aggregation pipeline for the stage. |
|--------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`validate`](#fiftyone.core.stages.Concat.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_edited_fields`](#fiftyone.core.stages.Concat.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.Concat.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.Concat.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.Concat.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.Concat.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.Concat.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.Concat.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.Concat.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* samples
The [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) whose
contents to append to this collection.
#### to_mongo(\_)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.Concat.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.Concat.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.Concat.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.Concat.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.Concat.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
### *class* fiftyone.core.stages.Exclude(sample_ids)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Excludes the samples with the given IDs from a collection.
Examples:
```default
import fiftyone as fo
dataset = fo.Dataset()
dataset.add_samples(
[
fo.Sample(filepath="/path/to/image1.png"),
fo.Sample(filepath="/path/to/image2.png"),
fo.Sample(filepath="/path/to/image3.png"),
]
)
#
# Exclude the first sample from the dataset
#
sample_id = dataset.first().id
stage = fo.Exclude(sample_id)
view = dataset.add_stage(stage)
#
# Exclude the first and last samples from the dataset
#
sample_ids = [dataset.first().id, dataset.last().id]
stage = fo.Exclude(sample_ids)
view = dataset.add_stage(stage)
```
* **Parameters:**
**sample_ids** –
the samples to exclude. Can be any of the following:
- a sample ID
- an iterable of sample IDs
- a [`fiftyone.core.sample.Sample`](fiftyone.core.sample.md#fiftyone.core.sample.Sample) or
[`fiftyone.core.sample.SampleView`](fiftyone.core.sample.md#fiftyone.core.sample.SampleView)
- an iterable of [`fiftyone.core.sample.Sample`](fiftyone.core.sample.md#fiftyone.core.sample.Sample) or
[`fiftyone.core.sample.SampleView`](fiftyone.core.sample.md#fiftyone.core.sample.SampleView) instances
- a [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
**Attributes:**
| [`sample_ids`](#fiftyone.core.stages.Exclude.sample_ids) | The list of sample IDs to exclude. |
|----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`flattens_groups`](#fiftyone.core.stages.Exclude.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.Exclude.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.Exclude.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.Exclude.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.Exclude.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.Exclude.to_mongo)(_) | Returns the MongoDB aggregation pipeline for the stage. |
|---------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_edited_fields`](#fiftyone.core.stages.Exclude.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.Exclude.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.Exclude.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.Exclude.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.Exclude.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.Exclude.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.Exclude.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.Exclude.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
| [`validate`](#fiftyone.core.stages.Exclude.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
#### *property* sample_ids
The list of sample IDs to exclude.
#### to_mongo(\_)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.Exclude.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.Exclude.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.Exclude.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.Exclude.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.Exclude.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
### *class* fiftyone.core.stages.ExcludeBy(field, values)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Excludes the samples with the given field values from a collection.
This stage is typically used to work with categorical fields (strings,
ints, and bools). If you want to exclude samples based on floating point
fields, use [`Match`](#fiftyone.core.stages.Match).
Examples:
```default
import fiftyone as fo
dataset = fo.Dataset()
dataset.add_samples(
[
fo.Sample(filepath="image%d.jpg" % i, int=i, str=str(i))
for i in range(10)
]
)
#
# Create a view excluding samples whose `int` field have the given
# values
#
stage = fo.ExcludeBy("int", [1, 9, 3, 7, 5])
view = dataset.add_stage(stage)
print(view.head(5))
#
# Create a view excluding samples whose `str` field have the given
# values
#
stage = fo.ExcludeBy("str", ["1", "9", "3", "7", "5"])
view = dataset.add_stage(stage)
print(view.head(5))
```
* **Parameters:**
* **field** – a field or `embedded.field.name`
* **values** – a value or iterable of values to exclude by
**Attributes:**
| [`field`](#fiftyone.core.stages.ExcludeBy.field) | The field whose values to exclude by. |
|------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`values`](#fiftyone.core.stages.ExcludeBy.values) | The list of values to exclude by. |
| [`flattens_groups`](#fiftyone.core.stages.ExcludeBy.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.ExcludeBy.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.ExcludeBy.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.ExcludeBy.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.ExcludeBy.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.ExcludeBy.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
|-----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_edited_fields`](#fiftyone.core.stages.ExcludeBy.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.ExcludeBy.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.ExcludeBy.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.ExcludeBy.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.ExcludeBy.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.ExcludeBy.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.ExcludeBy.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.ExcludeBy.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
| [`validate`](#fiftyone.core.stages.ExcludeBy.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
#### *property* field
The field whose values to exclude by.
#### *property* values
The list of values to exclude by.
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ExcludeBy.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.ExcludeBy.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.ExcludeBy.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.ExcludeBy.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ExcludeBy.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
### *class* fiftyone.core.stages.ExcludeFields(field_names=None, meta_filter=None, \_allow_missing=False)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Excludes the fields with the given names from the samples in a
collection.
Note that default fields cannot be excluded.
Examples:
```default
import fiftyone as fo
dataset = fo.Dataset()
dataset.add_samples(
[
fo.Sample(
filepath="/path/to/image1.png",
ground_truth=fo.Classification(label="cat"),
predictions=fo.Classification(
label="cat",
confidence=0.9,
mood="surly",
),
),
fo.Sample(
filepath="/path/to/image2.png",
ground_truth=fo.Classification(label="dog"),
predictions=fo.Classification(
label="dog",
confidence=0.8,
mood="happy",
),
),
fo.Sample(
filepath="/path/to/image3.png",
),
]
)
#
# Exclude the `predictions` field from all samples
#
stage = fo.ExcludeFields("predictions")
view = dataset.add_stage(stage)
#
# Exclude the `mood` attribute from all classifications in the
# `predictions` field
#
stage = fo.ExcludeFields("predictions.mood")
view = dataset.add_stage(stage)
#
# Exclude the `predictions` field from all samples
#
```
* **Parameters:**
* **field_names** (*None*) – a field name or iterable of field names to exclude.
May contain `embedded.field.name` as well
* **meta_filter** (*None*) –
a filter that dynamically excludes fields in
the collection’s schema according to the specified rule, which
can be matched against the field’s `name`, `type`,
`description`, and/or `info`. For example:
- Use `meta_filter="2023"` or `meta_filter={"any": "2023"}`
to exclude fields that have the string “2023” anywhere in their
name, type, description, or info
- Use `meta_filter={"type": "StringField"}` or
`meta_filter={"type": "Classification"}` to exclude all
string or classification fields, respectively
- Use `meta_filter={"description": "my description"}` to
exclude fields whose description contains the string
“my description”
- Use `meta_filter={"info": "2023"}` to exclude fields that
have the string “2023” anywhere in their info
- Use `meta_filter={"info.key": "value"}}` to exclude
fields that have a specific key/value pair in their info
- Include `meta_filter={"include_nested_fields": True, ...}` in
your meta filter to include all nested fields in the filter
**Attributes:**
| [`field_names`](#fiftyone.core.stages.ExcludeFields.field_names) | A list of field names to exclude. |
|----------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`meta_filter`](#fiftyone.core.stages.ExcludeFields.meta_filter) | A filter that dynamically excludes fields. |
| [`flattens_groups`](#fiftyone.core.stages.ExcludeFields.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.ExcludeFields.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.ExcludeFields.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.ExcludeFields.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.ExcludeFields.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`get_excluded_fields`](#fiftyone.core.stages.ExcludeFields.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
|-----------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`to_mongo`](#fiftyone.core.stages.ExcludeFields.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
| [`validate`](#fiftyone.core.stages.ExcludeFields.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_edited_fields`](#fiftyone.core.stages.ExcludeFields.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.ExcludeFields.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.ExcludeFields.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.ExcludeFields.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.ExcludeFields.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.ExcludeFields.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.ExcludeFields.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* field_names
A list of field names to exclude.
#### *property* meta_filter
A filter that dynamically excludes fields.
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ExcludeFields.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.ExcludeFields.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.ExcludeFields.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.ExcludeFields.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ExcludeFields.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
### *class* fiftyone.core.stages.ExcludeFrames(frame_ids, omit_empty=True)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Excludes the frames with the given IDs from a video collection.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("quickstart-video")
#
# Exclude some specific frames
#
frame_ids = [
dataset.first().frames.first().id,
dataset.last().frames.last().id,
]
stage = fo.ExcludeFrames(frame_ids)
view = dataset.add_stage(stage)
print(dataset.count("frames"))
print(view.count("frames"))
```
* **Parameters:**
* **frame_ids** –
the frames to exclude. Can be any of the following:
- a frame ID
- an iterable of frame IDs
- a [`fiftyone.core.frame.Frame`](fiftyone.core.frame.md#fiftyone.core.frame.Frame) or
[`fiftyone.core.frame.FrameView`](fiftyone.core.frame.md#fiftyone.core.frame.FrameView)
- an iterable of [`fiftyone.core.frame.Frame`](fiftyone.core.frame.md#fiftyone.core.frame.Frame) or
[`fiftyone.core.frame.FrameView`](fiftyone.core.frame.md#fiftyone.core.frame.FrameView) instances
- a [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) whose
frames to exclude
* **omit_empty** (*True*) – whether to omit samples that have no frames after
excluding the specified frames
**Attributes:**
| [`frame_ids`](#fiftyone.core.stages.ExcludeFrames.frame_ids) | The list of frame IDs to exclude. |
|----------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`omit_empty`](#fiftyone.core.stages.ExcludeFrames.omit_empty) | Whether to omit samples that have no frames after filtering. |
| [`flattens_groups`](#fiftyone.core.stages.ExcludeFrames.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.ExcludeFrames.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.ExcludeFrames.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.ExcludeFrames.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.ExcludeFrames.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.ExcludeFrames.to_mongo)(_) | Returns the MongoDB aggregation pipeline for the stage. |
|---------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`validate`](#fiftyone.core.stages.ExcludeFrames.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_edited_fields`](#fiftyone.core.stages.ExcludeFrames.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.ExcludeFrames.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.ExcludeFrames.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.ExcludeFrames.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.ExcludeFrames.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.ExcludeFrames.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.ExcludeFrames.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.ExcludeFrames.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* frame_ids
The list of frame IDs to exclude.
#### *property* omit_empty
Whether to omit samples that have no frames after filtering.
#### to_mongo(\_)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ExcludeFrames.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.ExcludeFrames.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.ExcludeFrames.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.ExcludeFrames.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ExcludeFrames.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
### *class* fiftyone.core.stages.ExcludeGroups(group_ids, ordered=False)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Excludes the groups with the given IDs from a grouped collection.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("quickstart-groups")
#
# Exclude some specific groups by ID
#
view = dataset.take(2)
group_ids = view.values("group.id")
stage = fo.ExcludeGroups(group_ids)
other_groups = dataset.add_stage(stage)
assert len(set(group_ids) & set(other_groups.values("group.id"))) == 0
```
* **Parameters:**
**groups_ids** –
the groups to select. Can be any of the following:
- a group ID
- an iterable of group IDs
- a [`fiftyone.core.sample.Sample`](fiftyone.core.sample.md#fiftyone.core.sample.Sample) or
[`fiftyone.core.sample.SampleView`](fiftyone.core.sample.md#fiftyone.core.sample.SampleView)
- a group dict returned by
[`get_group()`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection.get_group)
- an iterable of [`fiftyone.core.sample.Sample`](fiftyone.core.sample.md#fiftyone.core.sample.Sample) or
[`fiftyone.core.sample.SampleView`](fiftyone.core.sample.md#fiftyone.core.sample.SampleView) instances
- an iterable of group dicts returned by
[`get_group()`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection.get_group)
- a [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
**Attributes:**
| [`group_ids`](#fiftyone.core.stages.ExcludeGroups.group_ids) | The list of group IDs to exclude. |
|----------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`flattens_groups`](#fiftyone.core.stages.ExcludeGroups.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.ExcludeGroups.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.ExcludeGroups.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.ExcludeGroups.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.ExcludeGroups.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.ExcludeGroups.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
|---------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`validate`](#fiftyone.core.stages.ExcludeGroups.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_edited_fields`](#fiftyone.core.stages.ExcludeGroups.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.ExcludeGroups.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.ExcludeGroups.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.ExcludeGroups.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.ExcludeGroups.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.ExcludeGroups.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.ExcludeGroups.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.ExcludeGroups.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* group_ids
The list of group IDs to exclude.
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ExcludeGroups.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.ExcludeGroups.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.ExcludeGroups.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.ExcludeGroups.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ExcludeGroups.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
### *class* fiftyone.core.stages.ExcludeLabels(labels=None, ids=None, instance_ids=None, tags=None, fields=None, omit_empty=True)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Excludes the specified labels from a collection.
The returned view will omit samples, sample fields, and individual labels
that do not match the specified selection criteria.
You can perform an exclusion via one or more of the following methods:
- Provide the `labels` argument, which should contain a list of dicts
in the format returned by
[`fiftyone.core.session.Session.selected_labels`](fiftyone.core.session.md#fiftyone.core.session.Session.selected_labels), to exclude
specific labels
- Provide the `ids` argument to exclude labels with specific IDs
- Provide the `instance_ids` argument to exclude labels with specific
instance IDs
- Provide the `tags` argument to exclude labels with specific tags
If multiple criteria are specified, labels must match all of them in order
to be excluded.
By default, the exclusion is applied to all
[`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) fields, but you can provide the
`fields` argument to explicitly define the field(s) in which to exclude.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("quickstart")
#
# Exclude the labels currently selected in the App
#
session = fo.launch_app(dataset)
# Select some labels in the App...
stage = fo.ExcludeLabels(labels=session.selected_labels)
view = dataset.add_stage(stage)
#
# Exclude labels with the specified IDs
#
# Grab some label IDs
ids = [
dataset.first().ground_truth.detections[0].id,
dataset.last().predictions.detections[0].id,
]
stage = fo.ExcludeLabels(ids=ids)
view = dataset.add_stage(stage)
print(dataset.count("ground_truth.detections"))
print(view.count("ground_truth.detections"))
print(dataset.count("predictions.detections"))
print(view.count("predictions.detections"))
#
# Exclude labels with the specified tags
#
# Grab some label IDs
ids = [
dataset.first().ground_truth.detections[0].id,
dataset.last().predictions.detections[0].id,
]
# Give the labels a "test" tag
dataset = dataset.clone() # create copy since we're modifying data
dataset.select_labels(ids=ids).tag_labels("test")
print(dataset.count_values("ground_truth.detections.tags"))
print(dataset.count_values("predictions.detections.tags"))
# Exclude the labels via their tag
stage = fo.ExcludeLabels(tags="test")
view = dataset.add_stage(stage)
print(dataset.count("ground_truth.detections"))
print(view.count("ground_truth.detections"))
print(dataset.count("predictions.detections"))
print(view.count("predictions.detections"))
```
* **Parameters:**
* **labels** (*None*) – a list of dicts specifying the labels to exclude in the
format returned by
[`fiftyone.core.session.Session.selected_labels`](fiftyone.core.session.md#fiftyone.core.session.Session.selected_labels)
* **ids** (*None*) – an ID or iterable of IDs of the labels to exclude
* **instance_ids** (*None*) – an instance ID or iterable of instance IDs of the
labels to exclude
* **tags** (*None*) – a tag or iterable of tags of labels to exclude
* **fields** (*None*) – a field or iterable of fields from which to exclude
* **omit_empty** (*True*) – whether to omit samples that have no labels after
filtering
**Attributes:**
| [`labels`](#fiftyone.core.stages.ExcludeLabels.labels) | A list of dicts specifying the labels to exclude. |
|----------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`ids`](#fiftyone.core.stages.ExcludeLabels.ids) | A list of IDs of labels to exclude. |
| [`instance_ids`](#fiftyone.core.stages.ExcludeLabels.instance_ids) | A list of instance IDs of labels to exclude. |
| [`tags`](#fiftyone.core.stages.ExcludeLabels.tags) | A list of tags of labels to exclude. |
| [`fields`](#fiftyone.core.stages.ExcludeLabels.fields) | A list of fields from which labels are being excluded. |
| [`omit_empty`](#fiftyone.core.stages.ExcludeLabels.omit_empty) | Whether to omit samples that have no labels after filtering. |
| [`flattens_groups`](#fiftyone.core.stages.ExcludeLabels.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.ExcludeLabels.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.ExcludeLabels.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.ExcludeLabels.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.ExcludeLabels.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`get_edited_fields`](#fiftyone.core.stages.ExcludeLabels.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
|---------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_filtered_fields`](#fiftyone.core.stages.ExcludeLabels.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`to_mongo`](#fiftyone.core.stages.ExcludeLabels.to_mongo)(_) | Returns the MongoDB aggregation pipeline for the stage. |
| [`validate`](#fiftyone.core.stages.ExcludeLabels.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_excluded_fields`](#fiftyone.core.stages.ExcludeLabels.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.ExcludeLabels.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.ExcludeLabels.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.ExcludeLabels.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.ExcludeLabels.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.ExcludeLabels.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* labels
A list of dicts specifying the labels to exclude.
#### *property* ids
A list of IDs of labels to exclude.
#### *property* instance_ids
A list of instance IDs of labels to exclude.
#### *property* tags
A list of tags of labels to exclude.
#### *property* fields
A list of fields from which labels are being excluded.
#### *property* omit_empty
Whether to omit samples that have no labels after filtering.
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### to_mongo(\_)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ExcludeLabels.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.ExcludeLabels.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.ExcludeLabels.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.ExcludeLabels.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ExcludeLabels.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
### *class* fiftyone.core.stages.Exists(field, bool=None)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Returns a view containing the samples in a collection that have (or do
not have) a non-`None` value for the given field or embedded field.
Examples:
```default
import fiftyone as fo
dataset = fo.Dataset()
dataset.add_samples(
[
fo.Sample(
filepath="/path/to/image1.png",
ground_truth=fo.Classification(label="cat"),
predictions=fo.Classification(label="cat", confidence=0.9),
),
fo.Sample(
filepath="/path/to/image2.png",
ground_truth=fo.Classification(label="dog"),
predictions=fo.Classification(label="dog", confidence=0.8),
),
fo.Sample(
filepath="/path/to/image3.png",
ground_truth=fo.Classification(label="dog"),
predictions=fo.Classification(label="dog"),
),
fo.Sample(
filepath="/path/to/image4.png",
ground_truth=None,
predictions=None,
),
fo.Sample(filepath="/path/to/image5.png"),
]
)
#
# Only include samples that have a value in their `predictions` field
#
stage = fo.Exists("predictions")
view = dataset.add_stage(stage)
#
# Only include samples that do NOT have a value in their `predictions`
# field
#
stage = fo.Exists("predictions", False)
view = dataset.add_stage(stage)
#
# Only include samples that have prediction confidences
#
stage = fo.Exists("predictions.confidence")
view = dataset.add_stage(stage)
```
* **Parameters:**
* **field** – the field name or `embedded.field.name`
* **bool** (*True*) – whether to check if the field exists (None or True) or
does not exist (False)
**Attributes:**
| [`field`](#fiftyone.core.stages.Exists.field) | The field to check for existence. |
|---------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`bool`](#fiftyone.core.stages.Exists.bool) | Whether to check if the field exists (True) or does not exist (False). |
| [`flattens_groups`](#fiftyone.core.stages.Exists.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.Exists.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.Exists.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.Exists.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.Exists.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.Exists.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
|--------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_edited_fields`](#fiftyone.core.stages.Exists.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.Exists.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.Exists.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.Exists.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.Exists.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.Exists.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.Exists.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.Exists.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
| [`validate`](#fiftyone.core.stages.Exists.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
#### *property* field
The field to check for existence.
#### *property* bool
Whether to check if the field exists (True) or does not exist
(False).
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.Exists.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.Exists.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.Exists.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.Exists.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.Exists.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
### *class* fiftyone.core.stages.FilterField(field, filter, only_matches=True, \_new_field=None)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Filters the values of a given field or embedded field of each sample in
a collection.
Values of `field` for which `filter` returns `False` are
replaced with `None`.
Examples:
```default
import fiftyone as fo
from fiftyone import ViewField as F
dataset = fo.Dataset()
dataset.add_samples(
[
fo.Sample(
filepath="/path/to/image1.png",
ground_truth=fo.Classification(label="cat"),
predictions=fo.Classification(label="cat", confidence=0.9),
numeric_field=1.0,
),
fo.Sample(
filepath="/path/to/image2.png",
ground_truth=fo.Classification(label="dog"),
predictions=fo.Classification(label="dog", confidence=0.8),
numeric_field=-1.0,
),
fo.Sample(
filepath="/path/to/image3.png",
ground_truth=None,
predictions=None,
numeric_field=None,
),
]
)
#
# Only include classifications in the `predictions` field
# whose `label` is "cat"
#
stage = fo.FilterField("predictions", F("label") == "cat")
view = dataset.add_stage(stage)
#
# Only include samples whose `numeric_field` value is positive
#
stage = fo.FilterField("numeric_field", F() > 0)
view = dataset.add_stage(stage)
```
* **Parameters:**
* **field** – the field name or `embedded.field.name`
* **filter** – a [`fiftyone.core.expressions.ViewExpression`](fiftyone.core.expressions.md#fiftyone.core.expressions.ViewExpression) or
[MongoDB aggregation expression](https://docs.mongodb.com/manual/meta/aggregation-quick-reference/#aggregation-expressions)
that returns a boolean describing the filter to apply
* **only_matches** (*True*) – whether to only include samples that match the
filter (True) or include all samples (False)
**Attributes:**
| [`field`](#fiftyone.core.stages.FilterField.field) | The field to filter. |
|--------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`filter`](#fiftyone.core.stages.FilterField.filter) | The filter expression. |
| [`only_matches`](#fiftyone.core.stages.FilterField.only_matches) | Whether to only include samples that match the filter. |
| [`flattens_groups`](#fiftyone.core.stages.FilterField.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.FilterField.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.FilterField.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.FilterField.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.FilterField.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`get_edited_fields`](#fiftyone.core.stages.FilterField.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
|-------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`to_mongo`](#fiftyone.core.stages.FilterField.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
| [`validate`](#fiftyone.core.stages.FilterField.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_excluded_fields`](#fiftyone.core.stages.FilterField.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.FilterField.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.FilterField.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.FilterField.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.FilterField.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.FilterField.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.FilterField.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* field
The field to filter.
#### *property* filter
The filter expression.
#### *property* only_matches
Whether to only include samples that match the filter.
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.FilterField.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.FilterField.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.FilterField.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.FilterField.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.FilterField.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
### *class* fiftyone.core.stages.FilterLabels(field, filter, only_matches=True, trajectories=False, \_new_field=None, \_validate=True)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Filters the [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) field of each sample in
a collection.
If the specified `field` is a single [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label)
type, fields for which `filter` returns `False` are replaced with
`None`:
- [`fiftyone.core.labels.Classification`](fiftyone.core.labels.md#fiftyone.core.labels.Classification)
- [`fiftyone.core.labels.Detection`](fiftyone.core.labels.md#fiftyone.core.labels.Detection)
- [`fiftyone.core.labels.Polyline`](fiftyone.core.labels.md#fiftyone.core.labels.Polyline)
- [`fiftyone.core.labels.Keypoint`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoint)
If the specified `field` is a [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) list
type, the label elements for which `filter` returns `False` are omitted
from the view:
- [`fiftyone.core.labels.Classifications`](fiftyone.core.labels.md#fiftyone.core.labels.Classifications)
- [`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections)
- [`fiftyone.core.labels.Polylines`](fiftyone.core.labels.md#fiftyone.core.labels.Polylines)
- [`fiftyone.core.labels.Keypoints`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoints)
Classifications Examples:
```default
import fiftyone as fo
from fiftyone import ViewField as F
dataset = fo.Dataset()
dataset.add_samples(
[
fo.Sample(
filepath="/path/to/image1.png",
predictions=fo.Classification(label="cat", confidence=0.9),
),
fo.Sample(
filepath="/path/to/image2.png",
predictions=fo.Classification(label="dog", confidence=0.8),
),
fo.Sample(
filepath="/path/to/image3.png",
predictions=fo.Classification(label="rabbit"),
),
fo.Sample(
filepath="/path/to/image4.png",
predictions=None,
),
]
)
#
# Only include classifications in the `predictions` field whose
# `confidence` is greater than 0.8
#
stage = fo.FilterLabels("predictions", F("confidence") > 0.8)
view = dataset.add_stage(stage)
#
# Only include classifications in the `predictions` field whose `label`
# is "cat" or "dog"
#
stage = fo.FilterLabels("predictions", F("label").is_in(["cat", "dog"]))
view = dataset.add_stage(stage)
```
Detections Examples:
```default
import fiftyone as fo
from fiftyone import ViewField as F
dataset = fo.Dataset()
dataset.add_samples(
[
fo.Sample(
filepath="/path/to/image1.png",
predictions=fo.Detections(
detections=[
fo.Detection(
label="cat",
bounding_box=[0.1, 0.1, 0.5, 0.5],
confidence=0.9,
),
fo.Detection(
label="dog",
bounding_box=[0.2, 0.2, 0.3, 0.3],
confidence=0.8,
),
]
),
),
fo.Sample(
filepath="/path/to/image2.png",
predictions=fo.Detections(
detections=[
fo.Detection(
label="cat",
bounding_box=[0.5, 0.5, 0.4, 0.4],
confidence=0.95,
),
fo.Detection(label="rabbit"),
]
),
),
fo.Sample(
filepath="/path/to/image3.png",
predictions=fo.Detections(
detections=[
fo.Detection(
label="squirrel",
bounding_box=[0.25, 0.25, 0.5, 0.5],
confidence=0.5,
),
]
),
),
fo.Sample(
filepath="/path/to/image4.png",
predictions=None,
),
]
)
#
# Only include detections in the `predictions` field whose `confidence`
# is greater than 0.8
#
stage = fo.FilterLabels("predictions", F("confidence") > 0.8)
view = dataset.add_stage(stage)
#
# Only include detections in the `predictions` field whose `label` is
# "cat" or "dog"
#
stage = fo.FilterLabels("predictions", F("label").is_in(["cat", "dog"]))
view = dataset.add_stage(stage)
#
# Only include detections in the `predictions` field whose bounding box
# area is smaller than 0.2
#
# Bboxes are in [top-left-x, top-left-y, width, height] format
bbox_area = F("bounding_box")[2] * F("bounding_box")[3]
stage = fo.FilterLabels("predictions", bbox_area < 0.2)
view = dataset.add_stage(stage)
```
Polylines Examples:
```default
import fiftyone as fo
from fiftyone import ViewField as F
dataset = fo.Dataset()
dataset.add_samples(
[
fo.Sample(
filepath="/path/to/image1.png",
predictions=fo.Polylines(
polylines=[
fo.Polyline(
label="lane",
points=[[(0.1, 0.1), (0.1, 0.6)]],
filled=False,
),
fo.Polyline(
label="road",
points=[[(0.2, 0.2), (0.5, 0.5), (0.2, 0.5)]],
filled=True,
),
]
),
),
fo.Sample(
filepath="/path/to/image2.png",
predictions=fo.Polylines(
polylines=[
fo.Polyline(
label="lane",
points=[[(0.4, 0.4), (0.9, 0.4)]],
filled=False,
),
fo.Polyline(
label="road",
points=[[(0.6, 0.6), (0.9, 0.9), (0.6, 0.9)]],
filled=True,
),
]
),
),
fo.Sample(
filepath="/path/to/image3.png",
predictions=None,
),
]
)
#
# Only include polylines in the `predictions` field that are filled
#
stage = fo.FilterLabels("predictions", F("filled") == True)
view = dataset.add_stage(stage)
#
# Only include polylines in the `predictions` field whose `label` is
# "lane"
#
stage = fo.FilterLabels("predictions", F("label") == "lane")
view = dataset.add_stage(stage)
#
# Only include polylines in the `predictions` field with at least
# 3 vertices
#
num_vertices = F("points").map(F().length()).sum()
stage = fo.FilterLabels("predictions", num_vertices >= 3)
view = dataset.add_stage(stage)
```
Keypoints Examples:
```default
import fiftyone as fo
from fiftyone import ViewField as F
dataset = fo.Dataset()
dataset.add_samples(
[
fo.Sample(
filepath="/path/to/image1.png",
predictions=fo.Keypoint(
label="house",
points=[(0.1, 0.1), (0.1, 0.9), (0.9, 0.9), (0.9, 0.1)],
),
),
fo.Sample(
filepath="/path/to/image2.png",
predictions=fo.Keypoint(
label="window",
points=[(0.4, 0.4), (0.5, 0.5), (0.6, 0.6)],
),
),
fo.Sample(
filepath="/path/to/image3.png",
predictions=None,
),
]
)
#
# Only include keypoints in the `predictions` field whose `label` is
# "house"
#
stage = fo.FilterLabels("predictions", F("label") == "house")
view = dataset.add_stage(stage)
#
# Only include keypoints in the `predictions` field with less than four
# points
#
stage = fo.FilterLabels("predictions", F("points").length() < 4)
view = dataset.add_stage(stage)
```
* **Parameters:**
* **field** – the label field to filter
* **filter** –
a [`fiftyone.core.expressions.ViewExpression`](fiftyone.core.expressions.md#fiftyone.core.expressions.ViewExpression) or
[MongoDB aggregation expression](https://docs.mongodb.com/manual/meta/aggregation-quick-reference/#aggregation-expressions)
that returns a boolean describing the filter to apply
* **only_matches** (*True*) – whether to only include samples with at least
one label after filtering (True) or include all samples (False)
* **trajectories** (*False*) – whether to match entire object trajectories for
which the object matches the given filter on at least one frame.
Only applicable to video datasets and frame-level label fields
whose objects have their `index` attributes populated
**Attributes:**
| [`field`](#fiftyone.core.stages.FilterLabels.field) | The label field to filter. |
|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`filter`](#fiftyone.core.stages.FilterLabels.filter) | The filter expression. |
| [`only_matches`](#fiftyone.core.stages.FilterLabels.only_matches) | Whether to only include samples that match the filter. |
| [`trajectories`](#fiftyone.core.stages.FilterLabels.trajectories) | Whether to match entire object trajectories for which the object matches the given filter on at least one frame. |
| [`flattens_groups`](#fiftyone.core.stages.FilterLabels.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.FilterLabels.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.FilterLabels.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.FilterLabels.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.FilterLabels.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`get_edited_fields`](#fiftyone.core.stages.FilterLabels.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
|--------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_filtered_fields`](#fiftyone.core.stages.FilterLabels.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`to_mongo`](#fiftyone.core.stages.FilterLabels.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
| [`validate`](#fiftyone.core.stages.FilterLabels.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_excluded_fields`](#fiftyone.core.stages.FilterLabels.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.FilterLabels.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.FilterLabels.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.FilterLabels.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.FilterLabels.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.FilterLabels.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* field
The label field to filter.
#### *property* filter
The filter expression.
#### *property* only_matches
Whether to only include samples that match the filter.
#### *property* trajectories
Whether to match entire object trajectories for which the object
matches the given filter on at least one frame.
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.FilterLabels.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.FilterLabels.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.FilterLabels.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.FilterLabels.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.FilterLabels.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
### *class* fiftyone.core.stages.FilterKeypoints(field, filter=None, labels=None, only_matches=True, \_new_field=None)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Filters the individual [`fiftyone.core.labels.Keypoint.points`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoint.points)
elements in the specified keypoints field of each sample in the
collection.
#### NOTE
Use [`FilterLabels`](#fiftyone.core.stages.FilterLabels) if you simply want to filter entire
[`fiftyone.core.labels.Keypoint`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoint) objects in a field.
Examples:
```default
import fiftyone as fo
from fiftyone import ViewField as F
dataset = fo.Dataset()
dataset.add_samples(
[
fo.Sample(
filepath="/path/to/image1.png",
predictions=fo.Keypoints(
keypoints=[
fo.Keypoint(
label="person",
points=[(0.1, 0.1), (0.1, 0.9), (0.9, 0.9), (0.9, 0.1)],
confidence=[0.7, 0.8, 0.95, 0.99],
)
]
)
),
fo.Sample(filepath="/path/to/image2.png"),
]
)
dataset.default_skeleton = fo.KeypointSkeleton(
labels=["nose", "left eye", "right eye", "left ear", "right ear"],
edges=[[0, 1, 2, 0], [0, 3], [0, 4]],
)
#
# Only include keypoints in the `predictions` field whose
# `confidence` is greater than 0.9
#
stage = fo.FilterKeypoints("predictions", filter=F("confidence") > 0.9)
view = dataset.add_stage(stage)
#
# Only include keypoints in the `predictions` field with less than
# four points
#
stage = fo.FilterKeypoints("predictions", labels=["left eye", "right eye"])
view = dataset.add_stage(stage)
```
* **Parameters:**
* **field** – the [`fiftyone.core.labels.Keypoint`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoint) or
[`fiftyone.core.labels.Keypoints`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoints) field to filter
* **filter** (*None*) – a [`fiftyone.core.expressions.ViewExpression`](fiftyone.core.expressions.md#fiftyone.core.expressions.ViewExpression)
or [MongoDB expression](https://docs.mongodb.com/manual/meta/aggregation-quick-reference/#aggregation-expressions)
that returns a boolean, like `F("confidence") > 0.5` or
`F("occluded") == False`, to apply elementwise to the
specified field, which must be a list of same length as
[`fiftyone.core.labels.Keypoint.points`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoint.points)
* **labels** (*None*) – a label or iterable of keypoint skeleton labels to keep
* **only_matches** (*True*) – whether to only include keypoints/samples with
at least one point after filtering (True) or include all
keypoints/samples (False)
**Attributes:**
| [`filter`](#fiftyone.core.stages.FilterKeypoints.filter) | The filter expression. |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`labels`](#fiftyone.core.stages.FilterKeypoints.labels) | An iterable of keypoint skeleton labels to keep. |
| [`only_matches`](#fiftyone.core.stages.FilterKeypoints.only_matches) | Whether to only include samples that match the filter. |
| [`flattens_groups`](#fiftyone.core.stages.FilterKeypoints.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.FilterKeypoints.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.FilterKeypoints.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.FilterKeypoints.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.FilterKeypoints.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`get_edited_fields`](#fiftyone.core.stages.FilterKeypoints.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
|-----------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`to_mongo`](#fiftyone.core.stages.FilterKeypoints.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
| [`get_excluded_fields`](#fiftyone.core.stages.FilterKeypoints.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.FilterKeypoints.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.FilterKeypoints.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.FilterKeypoints.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.FilterKeypoints.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.FilterKeypoints.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.FilterKeypoints.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
| [`validate`](#fiftyone.core.stages.FilterKeypoints.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
#### *property* filter
The filter expression.
#### *property* labels
An iterable of keypoint skeleton labels to keep.
#### *property* only_matches
Whether to only include samples that match the filter.
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.FilterKeypoints.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.FilterKeypoints.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.FilterKeypoints.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.FilterKeypoints.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.FilterKeypoints.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
### *class* fiftyone.core.stages.GeoNear(point, location_field=None, min_distance=None, max_distance=None, query=None, create_index=False)
Bases: `_GeoStage`
Sorts the samples in a collection by their proximity to a specified
geolocation.
#### NOTE
This stage must be the **first stage** in any
[`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) in which it appears, and it
**requires** a spherical index on the specified location field.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
TIMES_SQUARE = [-73.9855, 40.7580]
dataset = foz.load_zoo_dataset("quickstart-geo")
#
# Sort the samples by their proximity to Times Square
#
stage = fo.GeoNear(TIMES_SQUARE, create_index=True)
view = dataset.add_stage(stage)
#
# Sort the samples by their proximity to Times Square, and only
# include samples within 5km
#
stage = fo.GeoNear(
TIMES_SQUARE,
max_distance=5000,
create_index=True,
)
view = dataset.add_stage(stage)
#
# Sort the samples by their proximity to Times Square, and only
# include samples that are in Manhattan
#
import fiftyone.utils.geojson as foug
in_manhattan = foug.geo_within(
"location.point",
[
[
[-73.949701, 40.834487],
[-73.896611, 40.815076],
[-73.998083, 40.696534],
[-74.031751, 40.715273],
[-73.949701, 40.834487],
]
]
)
stage = fo.GeoNear(
TIMES_SQUARE,
location_field="location",
query=in_manhattan,
create_index=True,
)
view = dataset.add_stage(stage)
```
* **Parameters:**
* **point** –
the reference point to compute distances to. Can be any of the
following:
- A `[longitude, latitude]` list
- A GeoJSON dict with `Point` type
- A [`fiftyone.core.labels.GeoLocation`](fiftyone.core.labels.md#fiftyone.core.labels.GeoLocation) instance whose
`point` attribute contains the point
* **location_field** (*None*) –
the location data of each sample to use. Can be
any of the following:
- The name of a `fiftyone.core.fields.GeoLocation` field
whose `point` attribute to use as location data
- An `embedded.field.name` containing GeoJSON data to use as
location data
- `None`, in which case there must be a single
`fiftyone.core.fields.GeoLocation` field on the samples,
which is used by default
* **min_distance** (*None*) – filter samples that are less than this distance
(in meters) from `point`
* **max_distance** (*None*) – filter samples that are greater than this distance
(in meters) from `point`
* **query** (*None*) – an optional dict defining a
[MongoDB read query](https://docs.mongodb.com/manual/tutorial/query-documents/#read-operations-query-argument)
that samples must match in order to be included in this view
* **create_index** (*False*) – whether to create the required spherical index,
if necessary
**Attributes:**
| [`point`](#fiftyone.core.stages.GeoNear.point) | The point to search proximity to. |
|----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`min_distance`](#fiftyone.core.stages.GeoNear.min_distance) | The minimum distance for matches, in meters. |
| [`max_distance`](#fiftyone.core.stages.GeoNear.max_distance) | The maximum distance for matches, in meters. |
| [`query`](#fiftyone.core.stages.GeoNear.query) | A query dict specifying a match condition. |
| [`create_index`](#fiftyone.core.stages.GeoNear.create_index) | Whether to create the relevant spherical index, if necessary. |
| [`flattens_groups`](#fiftyone.core.stages.GeoNear.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.GeoNear.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.GeoNear.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.GeoNear.to_mongo). |
| [`location_field`](#fiftyone.core.stages.GeoNear.location_field) | The location field. |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.GeoNear.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.GeoNear.to_mongo)(_, \*\*_\_) | Returns the MongoDB aggregation pipeline for the stage. |
|---------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_edited_fields`](#fiftyone.core.stages.GeoNear.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.GeoNear.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.GeoNear.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.GeoNear.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.GeoNear.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.GeoNear.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.GeoNear.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.GeoNear.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
| [`validate`](#fiftyone.core.stages.GeoNear.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
#### *property* point
The point to search proximity to.
#### *property* min_distance
The minimum distance for matches, in meters.
#### *property* max_distance
The maximum distance for matches, in meters.
#### *property* query
A query dict specifying a match condition.
#### to_mongo(\_, \*\*\_\_)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.GeoNear.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### *property* create_index
Whether to create the relevant spherical index, if necessary.
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.GeoNear.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.GeoNear.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.GeoNear.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.GeoNear.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* location_field
The location field.
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
### *class* fiftyone.core.stages.GeoWithin(boundary, location_field=None, strict=True, create_index=False)
Bases: `_GeoStage`
Filters the samples in a collection to only match samples whose
geolocation is within a specified boundary.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
MANHATTAN = [
[
[-73.949701, 40.834487],
[-73.896611, 40.815076],
[-73.998083, 40.696534],
[-74.031751, 40.715273],
[-73.949701, 40.834487],
]
]
dataset = foz.load_zoo_dataset("quickstart-geo")
#
# Create a view that only contains samples in Manhattan
#
stage = fo.GeoWithin(MANHATTAN)
view = dataset.add_stage(stage)
```
* **Parameters:**
* **boundary** – a [`fiftyone.core.labels.GeoLocation`](fiftyone.core.labels.md#fiftyone.core.labels.GeoLocation),
[`fiftyone.core.labels.GeoLocations`](fiftyone.core.labels.md#fiftyone.core.labels.GeoLocations), GeoJSON dict, or list
of coordinates that define a `Polygon` or `MultiPolygon` to
search within
* **location_field** (*None*) –
the location data of each sample to use. Can be
any of the following:
- The name of a `fiftyone.core.fields.GeoLocation` field
whose `point` attribute to use as location data
- An `embedded.field.name` that directly contains the GeoJSON
location data to use
- `None`, in which case there must be a single
`fiftyone.core.fields.GeoLocation` field on the samples,
which is used by default
* **strict** (*True*) – whether a sample’s location data must strictly fall
within boundary (True) in order to match, or whether any
intersection suffices (False)
* **create_index** (*False*) – whether to create a spherical index, if
necessary, to optimize the query
**Attributes:**
| [`boundary`](#fiftyone.core.stages.GeoWithin.boundary) | A GeoJSON dict describing the boundary to match within. |
|------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`strict`](#fiftyone.core.stages.GeoWithin.strict) | Whether matches must be strictly contained in the boundary. |
| [`create_index`](#fiftyone.core.stages.GeoWithin.create_index) | Whether to create the relevant spherical index, if necessary. |
| [`flattens_groups`](#fiftyone.core.stages.GeoWithin.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.GeoWithin.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.GeoWithin.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.GeoWithin.to_mongo). |
| [`location_field`](#fiftyone.core.stages.GeoWithin.location_field) | The location field. |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.GeoWithin.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.GeoWithin.to_mongo)(_, \*\*_\_) | Returns the MongoDB aggregation pipeline for the stage. |
|-----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_edited_fields`](#fiftyone.core.stages.GeoWithin.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.GeoWithin.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.GeoWithin.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.GeoWithin.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.GeoWithin.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.GeoWithin.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.GeoWithin.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.GeoWithin.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
| [`validate`](#fiftyone.core.stages.GeoWithin.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
#### *property* boundary
A GeoJSON dict describing the boundary to match within.
#### *property* strict
Whether matches must be strictly contained in the boundary.
#### to_mongo(\_, \*\*\_\_)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.GeoWithin.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### *property* create_index
Whether to create the relevant spherical index, if necessary.
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.GeoWithin.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.GeoWithin.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.GeoWithin.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.GeoWithin.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* location_field
The location field.
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
### *class* fiftyone.core.stages.GroupBy(field_or_expr, order_by=None, reverse=False, flat=False, match_expr=None, sort_expr=None, create_index=False, order_by_key=None)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Creates a view that groups the samples in a collection by a specified
field or expression.
Examples:
```default
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`](fiftyone.core.expressions.md#fiftyone.core.expressions.ViewExpression) or
[MongoDB aggregation expression](https://docs.mongodb.com/manual/meta/aggregation-quick-reference/#aggregation-expressions)
that defines the value to group by
* **order_by** (*None*) – an optional field by which to order the samples in
each group
* **reverse** (*False*) – whether to return the results in descending order.
Applies to both `order_by` and `sort_expr`
* **flat** (*False*) – whether to return a grouped collection (False) or a
flattened collection (True)
* **match_expr** (*None*) –
an optional
[`fiftyone.core.expressions.ViewExpression`](fiftyone.core.expressions.md#fiftyone.core.expressions.ViewExpression) or
[MongoDB aggregation expression](https://docs.mongodb.com/manual/meta/aggregation-quick-reference/#aggregation-expressions)
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** (*None*) –
an optional
[`fiftyone.core.expressions.ViewExpression`](fiftyone.core.expressions.md#fiftyone.core.expressions.ViewExpression) or
[MongoDB aggregation expression](https://docs.mongodb.com/manual/meta/aggregation-quick-reference/#aggregation-expressions)
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** (*False*) – whether to create an index, if necessary, to
optimize the grouping. Only applicable when grouping by field(s),
not expressions
* **order_by_key** (*None*) – an optional fixed `order_by` value representing
the first sample in a group. Required for optimized performance.
See [this guide](../user_guide/app.md#app-query-performant-stages) for more
details
**Attributes:**
| [`outputs_dynamic_groups`](#fiftyone.core.stages.GroupBy.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
|------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`field_or_expr`](#fiftyone.core.stages.GroupBy.field_or_expr) | The field or expression to group by. |
| [`order_by`](#fiftyone.core.stages.GroupBy.order_by) | The field by which to order the samples in each group. |
| [`order_by_key`](#fiftyone.core.stages.GroupBy.order_by_key) | The `order_by` value representing the first sample in a group. |
| [`reverse`](#fiftyone.core.stages.GroupBy.reverse) | Whether to sort the groups in descending order. |
| [`flat`](#fiftyone.core.stages.GroupBy.flat) | Whether to generate a flattened collection. |
| [`match_expr`](#fiftyone.core.stages.GroupBy.match_expr) | An expression to apply to select groups in the output view. |
| [`sort_expr`](#fiftyone.core.stages.GroupBy.sort_expr) | An expression defining how the sort the groups in the output view. |
| [`create_index`](#fiftyone.core.stages.GroupBy.create_index) | Whether to create an index, if necessary, to optimize the grouping. |
| [`flattens_groups`](#fiftyone.core.stages.GroupBy.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.GroupBy.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.GroupBy.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.GroupBy.to_mongo). |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.GroupBy.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
|---------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_group_expr`](#fiftyone.core.stages.GroupBy.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_media_type`](#fiftyone.core.stages.GroupBy.get_media_type)(sample_collection) | 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. |
| [`validate`](#fiftyone.core.stages.GroupBy.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_edited_fields`](#fiftyone.core.stages.GroupBy.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.GroupBy.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.GroupBy.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.GroupBy.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_selected_fields`](#fiftyone.core.stages.GroupBy.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.GroupBy.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### *property* field_or_expr
The field or expression to group by.
#### *property* order_by
The field by which to order the samples in each group.
#### *property* order_by_key
The `order_by` value representing the first sample in a group.
#### *property* reverse
Whether to sort the groups in descending order.
#### *property* flat
Whether to generate a flattened collection.
#### *property* match_expr
An expression to apply to select groups in the output view.
#### *property* sort_expr
An expression defining how the sort the groups in the output view.
#### *property* create_index
Whether to create an index, if necessary, to optimize the grouping.
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.GroupBy.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.GroupBy.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.GroupBy.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.GroupBy.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.GroupBy.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
### *class* fiftyone.core.stages.Flatten(stages=None)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Returns a flattened view that contains all samples in a dynamic grouped
collection.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("cifar10", split="test")
# Group samples by ground truth label
grouped_view = dataset.take(1000).group_by("ground_truth.label")
print(len(grouped_view)) # 10
# Return a flat view that contains 10 samples from each class
stage = fo.Flatten(fo.Limit(10))
flat_view = grouped_view.add_stage(stage)
print(len(flat_view)) # 100
```
* **Parameters:**
**stages** (*None*) – a [`ViewStage`](#fiftyone.core.stages.ViewStage) or list of [`ViewStage`](#fiftyone.core.stages.ViewStage)
instances to apply to each group’s samples while flattening
**Attributes:**
| [`outputs_dynamic_groups`](#fiftyone.core.stages.Flatten.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
|------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`stages`](#fiftyone.core.stages.Flatten.stages) | Stage(s) to apply to each group's samples while flattening. |
| [`flattens_groups`](#fiftyone.core.stages.Flatten.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.Flatten.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.Flatten.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.Flatten.to_mongo). |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.Flatten.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
|---------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_media_type`](#fiftyone.core.stages.Flatten.get_media_type)(sample_collection) | 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. |
| [`validate`](#fiftyone.core.stages.Flatten.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_edited_fields`](#fiftyone.core.stages.Flatten.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.Flatten.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.Flatten.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.Flatten.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.Flatten.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_selected_fields`](#fiftyone.core.stages.Flatten.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.Flatten.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### *property* stages
Stage(s) to apply to each group’s samples while flattening.
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.Flatten.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.Flatten.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.Flatten.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.Flatten.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.Flatten.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
### *class* fiftyone.core.stages.Limit(limit)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Creates a view with at most the given number of samples.
Examples:
```default
import fiftyone as fo
dataset = fo.Dataset()
dataset.add_samples(
[
fo.Sample(
filepath="/path/to/image1.png",
ground_truth=fo.Classification(label="cat"),
),
fo.Sample(
filepath="/path/to/image2.png",
ground_truth=fo.Classification(label="dog"),
),
fo.Sample(
filepath="/path/to/image3.png",
ground_truth=None,
),
]
)
#
# Only include the first 2 samples in the view
#
stage = fo.Limit(2)
view = dataset.add_stage(stage)
```
* **Parameters:**
**limit** – the maximum number of samples to return. If a non-positive
number is provided, an empty view is returned
**Attributes:**
| [`limit`](#fiftyone.core.stages.Limit.limit) | The maximum number of samples to return. |
|--------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`flattens_groups`](#fiftyone.core.stages.Limit.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.Limit.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.Limit.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.Limit.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.Limit.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.Limit.to_mongo)(_) | Returns the MongoDB aggregation pipeline for the stage. |
|-------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_edited_fields`](#fiftyone.core.stages.Limit.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.Limit.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.Limit.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.Limit.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.Limit.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.Limit.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.Limit.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.Limit.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
| [`validate`](#fiftyone.core.stages.Limit.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
#### *property* limit
The maximum number of samples to return.
#### to_mongo(\_)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.Limit.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.Limit.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.Limit.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.Limit.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.Limit.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
### *class* fiftyone.core.stages.LimitLabels(field, limit)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Limits the number of [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) instances in
the specified labels list field of each sample in a collection.
The specified `field` must be one of the following types:
- [`fiftyone.core.labels.Classifications`](fiftyone.core.labels.md#fiftyone.core.labels.Classifications)
- [`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections)
- [`fiftyone.core.labels.Keypoints`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoints)
- [`fiftyone.core.labels.Polylines`](fiftyone.core.labels.md#fiftyone.core.labels.Polylines)
Examples:
```default
import fiftyone as fo
from fiftyone import ViewField as F
dataset = fo.Dataset()
dataset.add_samples(
[
fo.Sample(
filepath="/path/to/image1.png",
predictions=fo.Detections(
detections=[
fo.Detection(
label="cat",
bounding_box=[0.1, 0.1, 0.5, 0.5],
confidence=0.9,
),
fo.Detection(
label="dog",
bounding_box=[0.2, 0.2, 0.3, 0.3],
confidence=0.8,
),
]
),
),
fo.Sample(
filepath="/path/to/image2.png",
predictions=fo.Detections(
detections=[
fo.Detection(
label="cat",
bounding_box=[0.5, 0.5, 0.4, 0.4],
confidence=0.95,
),
fo.Detection(label="rabbit"),
]
),
),
fo.Sample(
filepath="/path/to/image4.png",
predictions=None,
),
]
)
#
# Only include the first detection in the `predictions` field of each
# sample
#
stage = fo.LimitLabels("predictions", 1)
view = dataset.add_stage(stage)
```
* **Parameters:**
* **field** – the labels list field to filter
* **limit** – the maximum number of labels to include in each labels list.
If a non-positive number is provided, all lists will be empty
**Attributes:**
| [`field`](#fiftyone.core.stages.LimitLabels.field) | The labels field to limit. |
|--------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`limit`](#fiftyone.core.stages.LimitLabels.limit) | The maximum number of labels to allow in each labels list. |
| [`flattens_groups`](#fiftyone.core.stages.LimitLabels.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.LimitLabels.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.LimitLabels.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.LimitLabels.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.LimitLabels.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`get_edited_fields`](#fiftyone.core.stages.LimitLabels.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
|-------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_filtered_fields`](#fiftyone.core.stages.LimitLabels.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`to_mongo`](#fiftyone.core.stages.LimitLabels.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
| [`validate`](#fiftyone.core.stages.LimitLabels.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_excluded_fields`](#fiftyone.core.stages.LimitLabels.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.LimitLabels.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.LimitLabels.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.LimitLabels.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.LimitLabels.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.LimitLabels.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* field
The labels field to limit.
#### *property* limit
The maximum number of labels to allow in each labels list.
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.LimitLabels.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.LimitLabels.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.LimitLabels.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.LimitLabels.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.LimitLabels.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
### *class* fiftyone.core.stages.MapLabels(field, map)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Maps the `label` values of a [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) field
to new values for each sample in a collection.
Examples:
```default
import fiftyone as fo
from fiftyone import ViewField as F
dataset = fo.Dataset()
dataset.add_samples(
[
fo.Sample(
filepath="/path/to/image1.png",
weather=fo.Classification(label="sunny"),
predictions=fo.Detections(
detections=[
fo.Detection(
label="cat",
bounding_box=[0.1, 0.1, 0.5, 0.5],
confidence=0.9,
),
fo.Detection(
label="dog",
bounding_box=[0.2, 0.2, 0.3, 0.3],
confidence=0.8,
),
]
),
),
fo.Sample(
filepath="/path/to/image2.png",
weather=fo.Classification(label="cloudy"),
predictions=fo.Detections(
detections=[
fo.Detection(
label="cat",
bounding_box=[0.5, 0.5, 0.4, 0.4],
confidence=0.95,
),
fo.Detection(label="rabbit"),
]
),
),
fo.Sample(
filepath="/path/to/image3.png",
weather=fo.Classification(label="partly cloudy"),
predictions=fo.Detections(
detections=[
fo.Detection(
label="squirrel",
bounding_box=[0.25, 0.25, 0.5, 0.5],
confidence=0.5,
),
]
),
),
fo.Sample(
filepath="/path/to/image4.png",
predictions=None,
),
]
)
#
# Map the "partly cloudy" weather label to "cloudy"
#
stage = fo.MapLabels("weather", {"partly cloudy": "cloudy"})
view = dataset.add_stage(stage)
#
# Map "rabbit" and "squirrel" predictions to "other"
#
stage = fo.MapLabels(
"predictions", {"rabbit": "other", "squirrel": "other"}
)
view = dataset.add_stage(stage)
```
* **Parameters:**
* **field** – the labels field to map
* **map** – a dict mapping label values to new label values
**Attributes:**
| [`field`](#fiftyone.core.stages.MapLabels.field) | The labels field to map. |
|------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`map`](#fiftyone.core.stages.MapLabels.map) | The labels map dict. |
| [`flattens_groups`](#fiftyone.core.stages.MapLabels.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.MapLabels.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.MapLabels.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.MapLabels.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.MapLabels.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`get_edited_fields`](#fiftyone.core.stages.MapLabels.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
|-----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`to_mongo`](#fiftyone.core.stages.MapLabels.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
| [`validate`](#fiftyone.core.stages.MapLabels.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_excluded_fields`](#fiftyone.core.stages.MapLabels.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.MapLabels.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.MapLabels.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.MapLabels.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.MapLabels.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.MapLabels.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.MapLabels.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* field
The labels field to map.
#### *property* map
The labels map dict.
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.MapLabels.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.MapLabels.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.MapLabels.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.MapLabels.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.MapLabels.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
### *class* fiftyone.core.stages.MapValues(field, map)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Maps the values in the given field to new values for each sample in a
collection.
Examples:
```default
import random
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")
values = [random.choice(ANIMALS) for _ in range(len(dataset))]
dataset.set_values("str_field", values)
dataset.set_values("list_field", [[v] for v in values])
dataset.set_field("ground_truth.detections.tags", [F("label")]).save()
# Map all animals to string "animal"
mapping = {a: "animal" for a in ANIMALS}
#
# Map values in top-level fields
#
stage = fo.MapValues("str_field", mapping)
view = dataset.add_stage(stage)
print(view.count_values("str_field"))
# {"animal": 200}
stage = fo.MapValues("list_field", mapping)
view = dataset.add_stage(stage)
print(view.count_values("list_field"))
# {"animal": 200}
#
# Map values in nested fields
#
stage = fo.MapValues("ground_truth.detections.label", mapping)
view = dataset.add_stage(stage)
print(view.count_values("ground_truth.detections.label"))
# {"animal": 183, ...}
stage = fo.MapValues("ground_truth.detections.tags", mapping)
view = dataset.add_stage(stage)
print(view.count_values("ground_truth.detections.tags"))
# {"animal": 183, ...}
```
* **Parameters:**
* **field** – the field or `embedded.field.name` to map
* **map** – a dict mapping values to new values
**Attributes:**
| [`field`](#fiftyone.core.stages.MapValues.field) | The field to map. |
|------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`map`](#fiftyone.core.stages.MapValues.map) | The value map dict. |
| [`flattens_groups`](#fiftyone.core.stages.MapValues.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.MapValues.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.MapValues.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.MapValues.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.MapValues.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`get_edited_fields`](#fiftyone.core.stages.MapValues.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
|-----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`to_mongo`](#fiftyone.core.stages.MapValues.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
| [`get_excluded_fields`](#fiftyone.core.stages.MapValues.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.MapValues.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.MapValues.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.MapValues.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.MapValues.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.MapValues.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.MapValues.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
| [`validate`](#fiftyone.core.stages.MapValues.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
#### *property* field
The field to map.
#### *property* map
The value map dict.
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.MapValues.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.MapValues.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.MapValues.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.MapValues.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.MapValues.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
### *class* fiftyone.core.stages.SetField(field, expr, \_allow_missing=False, \_allow_limit=False)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Sets a field or embedded field on each sample in a collection by
evaluating the given expression.
This method can process embedded list fields. To do so, simply append
`[]` to any list component(s) of the field path.
#### NOTE
There are two cases where FiftyOne will automatically unwind array
fields without requiring you to explicitly specify this via the `[]`
syntax:
**Top-level lists:** when you specify a `field` path that refers to a
top-level list field of a dataset; i.e., `list_field` is
automatically coerced to `list_field[]`, if necessary.
**List fields:** When you specify a `field` path that refers to the
list field of a [`Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) class, such as the
[`Detections.detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections.detections)
attribute; i.e., `ground_truth.detections.label` is automatically
coerced to `ground_truth.detections[].label`, if necessary.
See the examples below for demonstrations of this behavior.
The provided `expr` is interpreted relative to the document on which the
embedded field is being set. For example, if you are setting a nested field
`field="embedded.document.field"`, then the expression `expr` you
provide will be applied to the `embedded.document` document. Note that
you can override this behavior by defining an expression that is bound to
the root document by prepending `"$"` to any field name(s) in the
expression.
See the examples below for more information.
#### NOTE
Note that you cannot set a non-existing top-level field using this
stage, since doing so would violate the dataset’s schema. You can,
however, first declare a new field via
[`fiftyone.core.dataset.Dataset.add_sample_field()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.add_sample_field) and then
populate it in a view via this stage.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
#
# Replace all values of uniqueness that are less than 0.5 with `None`
#
stage = fo.SetField(
"uniqueness",
(F("uniqueness") >= 0.5).if_else(F("uniqueness"), None)
)
view = dataset.add_stage(stage)
print(view.bounds("uniqueness"))
#
# Lower bound all object confidences in the `predictions` field by 0.5
#
stage = fo.SetField(
"predictions.detections.confidence", F("confidence").max(0.5)
)
view = dataset.add_stage(stage)
print(view.bounds("predictions.detections.confidence"))
#
# Add a `num_predictions` property to the `predictions` field that
# contains the number of objects in the field
#
stage = fo.SetField(
"predictions.num_predictions",
F("$predictions.detections").length(),
)
view = dataset.add_stage(stage)
print(view.bounds("predictions.num_predictions"))
#
# Set an `is_animal` field on each object in the `predictions` field
# that indicates whether the object is an animal
#
ANIMALS = [
"bear", "bird", "cat", "cow", "dog", "elephant", "giraffe",
"horse", "sheep", "zebra"
]
stage = fo.SetField(
"predictions.detections.is_animal", F("label").is_in(ANIMALS)
)
view = dataset.add_stage(stage)
print(view.count_values("predictions.detections.is_animal"))
```
* **Parameters:**
* **field** – the field or `embedded.field.name` to set
* **expr** –
a [`fiftyone.core.expressions.ViewExpression`](fiftyone.core.expressions.md#fiftyone.core.expressions.ViewExpression) or
[MongoDB aggregation expression](https://docs.mongodb.com/manual/meta/aggregation-quick-reference/#aggregation-expressions)
that defines the field value to set
**Attributes:**
| [`field`](#fiftyone.core.stages.SetField.field) | The field to set. |
|-----------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`expr`](#fiftyone.core.stages.SetField.expr) | The expression to apply. |
| [`flattens_groups`](#fiftyone.core.stages.SetField.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.SetField.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.SetField.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.SetField.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.SetField.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`get_edited_fields`](#fiftyone.core.stages.SetField.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
|----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`to_mongo`](#fiftyone.core.stages.SetField.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
| [`validate`](#fiftyone.core.stages.SetField.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_excluded_fields`](#fiftyone.core.stages.SetField.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.SetField.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.SetField.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.SetField.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.SetField.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.SetField.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.SetField.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* field
The field to set.
#### *property* expr
The expression to apply.
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.SetField.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.SetField.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.SetField.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.SetField.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.SetField.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
### *class* fiftyone.core.stages.Match(filter)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Filters the samples in the collection by the given filter.
Examples:
```default
import fiftyone as fo
from fiftyone import ViewField as F
dataset = fo.Dataset()
dataset.add_samples(
[
fo.Sample(
filepath="/path/to/image1.png",
weather=fo.Classification(label="sunny"),
predictions=fo.Detections(
detections=[
fo.Detection(
label="cat",
bounding_box=[0.1, 0.1, 0.5, 0.5],
confidence=0.9,
),
fo.Detection(
label="dog",
bounding_box=[0.2, 0.2, 0.3, 0.3],
confidence=0.8,
),
]
),
),
fo.Sample(
filepath="/path/to/image2.jpg",
weather=fo.Classification(label="cloudy"),
predictions=fo.Detections(
detections=[
fo.Detection(
label="cat",
bounding_box=[0.5, 0.5, 0.4, 0.4],
confidence=0.95,
),
fo.Detection(label="rabbit"),
]
),
),
fo.Sample(
filepath="/path/to/image3.png",
weather=fo.Classification(label="partly cloudy"),
predictions=fo.Detections(
detections=[
fo.Detection(
label="squirrel",
bounding_box=[0.25, 0.25, 0.5, 0.5],
confidence=0.5,
),
]
),
),
fo.Sample(
filepath="/path/to/image4.jpg",
predictions=None,
),
]
)
#
# Only include samples whose `filepath` ends with ".jpg"
#
stage = fo.Match(F("filepath").ends_with(".jpg"))
view = dataset.add_stage(stage)
#
# Only include samples whose `weather` field is "sunny"
#
stage = fo.Match(F("weather.label") == "sunny")
view = dataset.add_stage(stage)
#
# Only include samples with at least 2 objects in their `predictions`
# field
#
stage = fo.Match(F("predictions.detections").length() >= 2)
view = dataset.add_stage(stage)
#
# Only include samples whose `predictions` field contains at least one
# object with area smaller than 0.2
#
# Bboxes are in [top-left-x, top-left-y, width, height] format
bbox = F("bounding_box")
bbox_area = bbox[2] * bbox[3]
small_boxes = F("predictions.detections").filter(bbox_area < 0.2)
stage = fo.Match(small_boxes.length() > 0)
view = dataset.add_stage(stage)
```
* **Parameters:**
**filter** –
a [`fiftyone.core.expressions.ViewExpression`](fiftyone.core.expressions.md#fiftyone.core.expressions.ViewExpression) or
[MongoDB aggregation expression](https://docs.mongodb.com/manual/meta/aggregation-quick-reference/#aggregation-expressions)
that returns a boolean describing the filter to apply
**Attributes:**
| [`filter`](#fiftyone.core.stages.Match.filter) | The filter expression. |
|--------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`flattens_groups`](#fiftyone.core.stages.Match.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.Match.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.Match.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.Match.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.Match.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.Match.to_mongo)(_) | Returns the MongoDB aggregation pipeline for the stage. |
|-------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_edited_fields`](#fiftyone.core.stages.Match.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.Match.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.Match.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.Match.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.Match.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.Match.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.Match.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.Match.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
| [`validate`](#fiftyone.core.stages.Match.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
#### *property* filter
The filter expression.
#### to_mongo(\_)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.Match.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.Match.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.Match.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.Match.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.Match.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
### *class* fiftyone.core.stages.SelectGroupSlices(slices=None, media_type=None, flat=True, \_allow_mixed=False, \_force_mixed=False)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Selects the specified group slice(s) from a grouped collection.
When `flat==True`, the returned view is a flattened non-grouped view
containing the samples from the slice(s) of interest.
When `flat=False`, the returned view is a grouped collection containing
only the slice(s) of interest.
#### NOTE
When `flat=True`, this stage performs a `$lookup` that pulls the
requested slice(s) for each sample in the input collection from the
source dataset. As a result, the stage emits *unfiltered samples*.
Examples:
```default
import fiftyone as fo
dataset = fo.Dataset()
dataset.add_group_field("group", default="ego")
group1 = fo.Group()
group2 = fo.Group()
dataset.add_samples(
[
fo.Sample(
filepath="/path/to/left-image1.jpg",
group=group1.element("left"),
),
fo.Sample(
filepath="/path/to/video1.mp4",
group=group1.element("ego"),
),
fo.Sample(
filepath="/path/to/right-image1.jpg",
group=group1.element("right"),
),
fo.Sample(
filepath="/path/to/left-image2.jpg",
group=group2.element("left"),
),
fo.Sample(
filepath="/path/to/video2.mp4",
group=group2.element("ego"),
),
fo.Sample(
filepath="/path/to/right-image2.jpg",
group=group2.element("right"),
),
]
)
#
# Retrieve the samples from the "ego" group slice
#
stage = fo.SelectGroupSlices("ego")
view = dataset.add_stage(stage)
#
# Retrieve the samples from the "left" or "right" group slices
#
stage = fo.SelectGroupSlices(["left", "right"])
view = dataset.add_stage(stage)
#
# Select only the "left" and "right" group slices
#
stage = fo.SelectGroupSlices(["left", "right"], flat=False)
view = dataset.add_stage(stage)
#
# Retrieve all image samples
#
stage = fo.SelectGroupSlices(media_type="image")
view = dataset.add_stage(stage)
```
* **Parameters:**
* **slices** (*None*) – a group slice or iterable of group slices to select.
If neither argument is provided, a flattened list of all samples is
returned
* **media_type** (*None*) – a media type or iterable of media types whose
slice(s) to select
* **flat** (*True*) – whether to return a flattened collection (True) or a
grouped collection (False)
**Attributes:**
| [`slices`](#fiftyone.core.stages.SelectGroupSlices.slices) | The group slice(s) to select. |
|--------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`media_type`](#fiftyone.core.stages.SelectGroupSlices.media_type) | The media type(s) whose slices to select. |
| [`flat`](#fiftyone.core.stages.SelectGroupSlices.flat) | Whether to generate a flattened collection. |
| [`flattens_groups`](#fiftyone.core.stages.SelectGroupSlices.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.SelectGroupSlices.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.SelectGroupSlices.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.SelectGroupSlices.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.SelectGroupSlices.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.SelectGroupSlices.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
|-------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_media_type`](#fiftyone.core.stages.SelectGroupSlices.get_media_type)(sample_collection) | 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. |
| [`validate`](#fiftyone.core.stages.SelectGroupSlices.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_group_media_types`](#fiftyone.core.stages.SelectGroupSlices.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_edited_fields`](#fiftyone.core.stages.SelectGroupSlices.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.SelectGroupSlices.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.SelectGroupSlices.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.SelectGroupSlices.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_selected_fields`](#fiftyone.core.stages.SelectGroupSlices.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.SelectGroupSlices.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* slices
The group slice(s) to select.
#### *property* media_type
The media type(s) whose slices to select.
#### *property* flat
Whether to generate a flattened collection.
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.SelectGroupSlices.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.SelectGroupSlices.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.SelectGroupSlices.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.SelectGroupSlices.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.SelectGroupSlices.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
### *class* fiftyone.core.stages.ExcludeGroupSlices(slices=None, media_type=None)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Excludes the specified group slice(s) from a grouped collection.
Examples:
```default
import fiftyone as fo
dataset = fo.Dataset()
dataset.add_group_field("group", default="ego")
group1 = fo.Group()
group2 = fo.Group()
dataset.add_samples(
[
fo.Sample(
filepath="/path/to/left-image1.jpg",
group=group1.element("left"),
),
fo.Sample(
filepath="/path/to/video1.mp4",
group=group1.element("ego"),
),
fo.Sample(
filepath="/path/to/right-image1.jpg",
group=group1.element("right"),
),
fo.Sample(
filepath="/path/to/left-image2.jpg",
group=group2.element("left"),
),
fo.Sample(
filepath="/path/to/video2.mp4",
group=group2.element("ego"),
),
fo.Sample(
filepath="/path/to/right-image2.jpg",
group=group2.element("right"),
),
]
)
#
# Exclude the "ego" group slice
#
stage = fo.ExcludeGroupSlices("ego")
view = dataset.add_stage(stage)
#
# Exclude the "left" and "right" group slices
#
stage = fo.ExcludeGroupSlices(["left", "right"])
view = dataset.add_stage(stage)
#
# Exclude all image slices
#
stage = fo.ExcludeGroupSlices(media_type="image")
view = dataset.add_stage(stage)
```
* **Parameters:**
* **slices** (*None*) – a group slice or iterable of group slices to exclude.
* **media_type** (*None*) – a media type or iterable of media types whose
slice(s) to exclude
**Attributes:**
| [`slices`](#fiftyone.core.stages.ExcludeGroupSlices.slices) | The group slice(s) to exclude. |
|---------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`media_type`](#fiftyone.core.stages.ExcludeGroupSlices.media_type) | The media type(s) whose slices to exclude. |
| [`flattens_groups`](#fiftyone.core.stages.ExcludeGroupSlices.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.ExcludeGroupSlices.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.ExcludeGroupSlices.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.ExcludeGroupSlices.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.ExcludeGroupSlices.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.ExcludeGroupSlices.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
|--------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`validate`](#fiftyone.core.stages.ExcludeGroupSlices.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_group_media_types`](#fiftyone.core.stages.ExcludeGroupSlices.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_edited_fields`](#fiftyone.core.stages.ExcludeGroupSlices.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.ExcludeGroupSlices.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.ExcludeGroupSlices.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.ExcludeGroupSlices.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_media_type`](#fiftyone.core.stages.ExcludeGroupSlices.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.ExcludeGroupSlices.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.ExcludeGroupSlices.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* slices
The group slice(s) to exclude.
#### *property* media_type
The media type(s) whose slices to exclude.
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ExcludeGroupSlices.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.ExcludeGroupSlices.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.ExcludeGroupSlices.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.ExcludeGroupSlices.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ExcludeGroupSlices.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
### *class* fiftyone.core.stages.MatchFrames(filter, omit_empty=True)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Filters the frames in a video collection by the given filter.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart-video")
#
# Match frames with at least 10 detections
#
num_objects = F("detections.detections").length()
stage = fo.MatchFrames(num_objects > 10)
view = dataset.add_stage(stage)
print(dataset.count())
print(view.count())
print(dataset.count("frames"))
print(view.count("frames"))
```
* **Parameters:**
* **filter** –
a [`fiftyone.core.expressions.ViewExpression`](fiftyone.core.expressions.md#fiftyone.core.expressions.ViewExpression) or
[MongoDB aggregation expression](https://docs.mongodb.com/manual/meta/aggregation-quick-reference/#aggregation-expressions)
that returns a boolean describing the filter to apply
* **omit_empty** (*True*) – whether to omit samples with no frame labels after
filtering
**Attributes:**
| [`filter`](#fiftyone.core.stages.MatchFrames.filter) | The filter expression. |
|--------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`omit_empty`](#fiftyone.core.stages.MatchFrames.omit_empty) | Whether to omit samples that have no frames after filtering. |
| [`flattens_groups`](#fiftyone.core.stages.MatchFrames.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.MatchFrames.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.MatchFrames.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.MatchFrames.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.MatchFrames.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.MatchFrames.to_mongo)(_) | Returns the MongoDB aggregation pipeline for the stage. |
|-------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`validate`](#fiftyone.core.stages.MatchFrames.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_edited_fields`](#fiftyone.core.stages.MatchFrames.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.MatchFrames.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.MatchFrames.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.MatchFrames.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.MatchFrames.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.MatchFrames.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.MatchFrames.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.MatchFrames.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* filter
The filter expression.
#### *property* omit_empty
Whether to omit samples that have no frames after filtering.
#### to_mongo(\_)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.MatchFrames.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.MatchFrames.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.MatchFrames.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.MatchFrames.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.MatchFrames.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
### *class* fiftyone.core.stages.MatchLabels(labels=None, ids=None, instance_ids=None, tags=None, filter=None, fields=None, bool=None)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Selects the samples from a collection that contain (or do not contain)
at least one label that matches the specified criteria.
Note that, unlike [`SelectLabels`](#fiftyone.core.stages.SelectLabels) and [`FilterLabels`](#fiftyone.core.stages.FilterLabels), this
stage will not filter the labels themselves; it only selects the
corresponding samples.
You can perform a selection via one or more of the following methods:
- Provide the `labels` argument, which should contain a list of dicts
in the format returned by
[`fiftyone.core.session.Session.selected_labels`](fiftyone.core.session.md#fiftyone.core.session.Session.selected_labels), to match
specific labels
- Provide the `ids` argument to match labels with specific IDs
- Provide the `instance_ids` argument to match labels with specific
instance IDs
- Provide the `tags` argument to match labels with specific tags
- Provide the `filter` argument to match labels based on a boolean
[`fiftyone.core.expressions.ViewExpression`](fiftyone.core.expressions.md#fiftyone.core.expressions.ViewExpression) that is applied to
each individual [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) element
- Pass `bool=False` to negate the operation and instead match samples
that *do not* contain at least one label matching the specified
criteria
If multiple criteria are specified, labels must match all of them in order
to trigger a sample match.
By default, the selection is applied to all
[`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) fields, but you can provide the
`fields` argument to explicitly define the field(s) in which to search.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
#
# Only show samples whose labels are currently selected in the App
#
session = fo.launch_app(dataset)
# Select some labels in the App...
stage = fo.MatchLabels(labels=session.selected_labels)
view = dataset.add_stage(stage)
#
# Only include samples that contain labels with the specified IDs
#
# Grab some label IDs
ids = [
dataset.first().ground_truth.detections[0].id,
dataset.last().predictions.detections[0].id,
]
stage = fo.MatchLabels(ids=ids)
view = dataset.add_stage(stage)
print(len(view))
print(view.count("ground_truth.detections"))
print(view.count("predictions.detections"))
#
# Only include samples that contain labels with the specified tags
#
# Grab some label IDs
ids = [
dataset.first().ground_truth.detections[0].id,
dataset.last().predictions.detections[0].id,
]
# Give the labels a "test" tag
dataset = dataset.clone() # create copy since we're modifying data
dataset.select_labels(ids=ids).tag_labels("test")
print(dataset.count_values("ground_truth.detections.tags"))
print(dataset.count_values("predictions.detections.tags"))
# Retrieve the labels via their tag
stage = fo.MatchLabels(tags="test")
view = dataset.add_stage(stage)
print(len(view))
print(view.count("ground_truth.detections"))
print(view.count("predictions.detections"))
#
# Only include samples that contain labels matching a filter
#
filter = F("confidence") > 0.99
stage = fo.MatchLabels(filter=filter, fields="predictions")
view = dataset.add_stage(stage)
print(len(view))
print(view.count("ground_truth.detections"))
print(view.count("predictions.detections"))
```
* **Parameters:**
* **labels** (*None*) – a list of dicts specifying the labels to select in the
format returned by
[`fiftyone.core.session.Session.selected_labels`](fiftyone.core.session.md#fiftyone.core.session.Session.selected_labels)
* **ids** (*None*) – an ID or iterable of IDs of the labels to select
* **instance_ids** (*None*) – an instance ID or iterable of instance IDs of the
labels to select
* **tags** (*None*) – a tag or iterable of tags of labels to select
* **filter** (*None*) –
a [`fiftyone.core.expressions.ViewExpression`](fiftyone.core.expressions.md#fiftyone.core.expressions.ViewExpression) or
[MongoDB aggregation expression](https://docs.mongodb.com/manual/meta/aggregation-quick-reference/#aggregation-expressions)
that returns a boolean describing whether to select a given label.
In the case of list fields like
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections), the filter is applied to
the list elements, not the root field
* **fields** (*None*) – a field or iterable of fields from which to select
* **bool** (*None*) – whether to match samples that have (None or True) or do
not have (False) at least one label that matches the specified
criteria
**Attributes:**
| [`labels`](#fiftyone.core.stages.MatchLabels.labels) | A list of dicts specifying the labels to match. |
|--------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`ids`](#fiftyone.core.stages.MatchLabels.ids) | A list of IDs of labels to match. |
| [`instance_ids`](#fiftyone.core.stages.MatchLabels.instance_ids) | A list of instance IDs of labels to match. |
| [`tags`](#fiftyone.core.stages.MatchLabels.tags) | A list of tags of labels to match. |
| [`filter`](#fiftyone.core.stages.MatchLabels.filter) | A filter expression that defines the labels to match. |
| [`fields`](#fiftyone.core.stages.MatchLabels.fields) | A list of fields from which labels are being matched. |
| [`bool`](#fiftyone.core.stages.MatchLabels.bool) | Whether to match samples that have (None or True) or do not have (False) at least one label that matches the specified criteria. |
| [`flattens_groups`](#fiftyone.core.stages.MatchLabels.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.MatchLabels.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.MatchLabels.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.MatchLabels.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.MatchLabels.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.MatchLabels.to_mongo)(_) | Returns the MongoDB aggregation pipeline for the stage. |
|-------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`validate`](#fiftyone.core.stages.MatchLabels.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_edited_fields`](#fiftyone.core.stages.MatchLabels.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.MatchLabels.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.MatchLabels.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.MatchLabels.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.MatchLabels.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.MatchLabels.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.MatchLabels.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.MatchLabels.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* labels
A list of dicts specifying the labels to match.
#### *property* ids
A list of IDs of labels to match.
#### *property* instance_ids
A list of instance IDs of labels to match.
#### *property* tags
A list of tags of labels to match.
#### *property* filter
A filter expression that defines the labels to match.
#### *property* fields
A list of fields from which labels are being matched.
#### *property* bool
Whether to match samples that have (None or True) or do not have
(False) at least one label that matches the specified criteria.
#### to_mongo(\_)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.MatchLabels.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.MatchLabels.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.MatchLabels.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.MatchLabels.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.MatchLabels.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
### *class* fiftyone.core.stages.MatchTags(tags, bool=None, all=False)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Returns a view containing the samples in the collection that have or
don’t have any/all of the given tag(s).
Examples:
```default
import fiftyone as fo
dataset = fo.Dataset()
dataset.add_samples(
[
fo.Sample(filepath="image1.png", tags=["train"]),
fo.Sample(filepath="image2.png", tags=["test"]),
fo.Sample(filepath="image3.png", tags=["train", "test"]),
fo.Sample(filepath="image4.png"),
]
)
#
# Only include samples that have the "test" tag
#
stage = fo.MatchTags("test")
view = dataset.add_stage(stage)
#
# Only include samples that do not have the "test" tag
#
stage = fo.MatchTags("test", bool=False)
view = dataset.add_stage(stage)
#
# Only include samples that have the "test" or "train" tags
#
stage = fo.MatchTags(["test", "train"])
view = dataset.add_stage(stage)
#
# Only include samples that have the "test" and "train" tags
#
stage = fo.MatchTags(["test", "train"], all=True)
view = dataset.add_stage(stage)
#
# Only include samples that do not have the "test" or "train" tags
#
stage = fo.MatchTags(["test", "train"], bool=False)
view = dataset.add_stage(stage)
#
# Only include samples that do not have the "test" and "train" tags
#
stage = fo.MatchTags(["test", "train"], bool=False, all=True)
view = dataset.add_stage(stage)
```
* **Parameters:**
* **tags** – the tag or iterable of tags to match
* **bool** (*None*) – whether to match samples that have (None or True) or do
not have (False) the given tags
* **all** (*False*) – whether to match samples that have (or don’t have) all
(True) or any (None or False) of the given tags
**Attributes:**
| [`tags`](#fiftyone.core.stages.MatchTags.tags) | The list of tags to match. |
|------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`bool`](#fiftyone.core.stages.MatchTags.bool) | Whether to match samples that have (True) or do not have (False) any of the given tags. |
| [`all`](#fiftyone.core.stages.MatchTags.all) | Whether to match samples that have (or don't have) all (True) or any (False) of the given tags. |
| [`flattens_groups`](#fiftyone.core.stages.MatchTags.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.MatchTags.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.MatchTags.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.MatchTags.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.MatchTags.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.MatchTags.to_mongo)(_) | Returns the MongoDB aggregation pipeline for the stage. |
|-----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_edited_fields`](#fiftyone.core.stages.MatchTags.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.MatchTags.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.MatchTags.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.MatchTags.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.MatchTags.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.MatchTags.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.MatchTags.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.MatchTags.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
| [`validate`](#fiftyone.core.stages.MatchTags.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
#### *property* tags
The list of tags to match.
#### *property* bool
Whether to match samples that have (True) or do not have (False) any
of the given tags.
#### *property* all
Whether to match samples that have (or don’t have) all (True) or any
(False) of the given tags.
#### to_mongo(\_)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.MatchTags.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.MatchTags.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.MatchTags.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.MatchTags.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.MatchTags.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
### *class* fiftyone.core.stages.Mongo(pipeline, \_needs_frames=None, \_group_slices=None)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
A view stage defined by a raw MongoDB aggregation pipeline.
See [MongoDB aggregation pipelines](https://docs.mongodb.com/manual/core/aggregation-pipeline/)
for more details.
Examples:
```default
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",
bounding_box=[0.1, 0.1, 0.5, 0.5],
confidence=0.9,
),
fo.Detection(
label="dog",
bounding_box=[0.2, 0.2, 0.3, 0.3],
confidence=0.8,
),
]
),
),
fo.Sample(
filepath="/path/to/image2.png",
predictions=fo.Detections(
detections=[
fo.Detection(
label="cat",
bounding_box=[0.5, 0.5, 0.4, 0.4],
confidence=0.95,
),
fo.Detection(label="rabbit"),
]
),
),
fo.Sample(
filepath="/path/to/image3.png",
predictions=fo.Detections(
detections=[
fo.Detection(
label="squirrel",
bounding_box=[0.25, 0.25, 0.5, 0.5],
confidence=0.5,
),
]
),
),
fo.Sample(
filepath="/path/to/image4.png",
predictions=None,
),
]
)
#
# Extract a view containing the second and third samples in the dataset
#
stage = fo.Mongo([{"$skip": 1}, {"$limit": 2}])
view = dataset.add_stage(stage)
#
# Sort by the number of objects in the `precictions` field
#
stage = fo.Mongo([
{
"$addFields": {
"_sort_field": {
"$size": {"$ifNull": ["$predictions.detections", []]}
}
}
},
{"$sort": {"_sort_field": -1}},
{"$project": {"_sort_field": False}},
])
view = dataset.add_stage(stage)
```
* **Parameters:**
**pipeline** – a MongoDB aggregation pipeline (list of dicts)
**Attributes:**
| [`pipeline`](#fiftyone.core.stages.Mongo.pipeline) | The MongoDB aggregation pipeline. |
|--------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`flattens_groups`](#fiftyone.core.stages.Mongo.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.Mongo.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.Mongo.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.Mongo.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.Mongo.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.Mongo.to_mongo)(_) | Returns the MongoDB aggregation pipeline for the stage. |
|-------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_edited_fields`](#fiftyone.core.stages.Mongo.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.Mongo.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.Mongo.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.Mongo.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.Mongo.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.Mongo.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.Mongo.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.Mongo.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
| [`validate`](#fiftyone.core.stages.Mongo.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
#### *property* pipeline
The MongoDB aggregation pipeline.
#### to_mongo(\_)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.Mongo.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.Mongo.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.Mongo.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.Mongo.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.Mongo.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
### *class* fiftyone.core.stages.Select(sample_ids, ordered=False)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Selects the samples with the given IDs from a collection.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("quickstart")
#
# Create a view containing the currently selected samples in the App
#
session = fo.launch_app(dataset)
# Select samples in the App...
stage = fo.Select(session.selected)
view = dataset.add_stage(stage)
```
* **Parameters:**
* **sample_ids** –
the samples to select. Can be any of the following:
- a sample ID
- an iterable of sample IDs
- an iterable of booleans of same length as the collection
encoding which samples to select
- a [`fiftyone.core.sample.Sample`](fiftyone.core.sample.md#fiftyone.core.sample.Sample) or
[`fiftyone.core.sample.SampleView`](fiftyone.core.sample.md#fiftyone.core.sample.SampleView)
- an iterable of [`fiftyone.core.sample.Sample`](fiftyone.core.sample.md#fiftyone.core.sample.Sample) or
[`fiftyone.core.sample.SampleView`](fiftyone.core.sample.md#fiftyone.core.sample.SampleView) instances
- a [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **ordered** (*False*) – whether to sort the samples in the returned view to
match the order of the provided IDs
**Attributes:**
| [`sample_ids`](#fiftyone.core.stages.Select.sample_ids) | The list of sample IDs to select. |
|---------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`ordered`](#fiftyone.core.stages.Select.ordered) | Whether to sort the samples in the same order as the IDs. |
| [`flattens_groups`](#fiftyone.core.stages.Select.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.Select.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.Select.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.Select.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.Select.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.Select.to_mongo)(_) | Returns the MongoDB aggregation pipeline for the stage. |
|--------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`validate`](#fiftyone.core.stages.Select.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_edited_fields`](#fiftyone.core.stages.Select.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.Select.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.Select.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.Select.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.Select.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.Select.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.Select.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.Select.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* sample_ids
The list of sample IDs to select.
#### *property* ordered
Whether to sort the samples in the same order as the IDs.
#### to_mongo(\_)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.Select.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.Select.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.Select.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.Select.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.Select.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
### *class* fiftyone.core.stages.SelectBy(field, values, ordered=False)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Selects the samples with the given field values from a collection.
This stage is typically used to work with categorical fields (strings,
ints, and bools). If you want to select samples based on floating point
fields, use [`Match`](#fiftyone.core.stages.Match).
Examples:
```default
import fiftyone as fo
dataset = fo.Dataset()
dataset.add_samples(
[
fo.Sample(filepath="image%d.jpg" % i, int=i, str=str(i))
for i in range(100)
]
)
#
# Create a view containing samples whose `int` field have the given
# values
#
stage = fo.SelectBy("int", [1, 51, 11, 41, 21, 31])
view = dataset.add_stage(stage)
print(view.head(6))
#
# Create a view containing samples whose `str` field have the given
# values, in order
#
stage = fo.SelectBy(
"str", ["1", "51", "11", "41", "21", "31"], ordered=True
)
view = dataset.add_stage(stage)
print(view.head(6))
```
* **Parameters:**
* **field** – a field or `embedded.field.name`
* **values** – a value or iterable of values to select by
* **ordered** (*False*) – whether to sort the samples in the returned view to
match the order of the provided values
**Attributes:**
| [`field`](#fiftyone.core.stages.SelectBy.field) | The field whose values to select by. |
|-----------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`values`](#fiftyone.core.stages.SelectBy.values) | The list of values to select by. |
| [`ordered`](#fiftyone.core.stages.SelectBy.ordered) | Whether to sort the samples in the same order as the IDs. |
| [`flattens_groups`](#fiftyone.core.stages.SelectBy.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.SelectBy.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.SelectBy.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.SelectBy.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.SelectBy.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.SelectBy.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
|----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_edited_fields`](#fiftyone.core.stages.SelectBy.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.SelectBy.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.SelectBy.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.SelectBy.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.SelectBy.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.SelectBy.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.SelectBy.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.SelectBy.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
| [`validate`](#fiftyone.core.stages.SelectBy.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
#### *property* field
The field whose values to select by.
#### *property* values
The list of values to select by.
#### *property* ordered
Whether to sort the samples in the same order as the IDs.
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.SelectBy.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.SelectBy.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.SelectBy.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.SelectBy.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.SelectBy.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
### *class* fiftyone.core.stages.SelectFields(field_names=None, meta_filter=None, \_allow_missing=False, \_media_types=None)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Selects only the fields with the given names from the samples in the
collection. All other fields are excluded.
Note that default sample fields are always selected.
Examples:
```default
import fiftyone as fo
dataset = fo.Dataset()
dataset.add_samples(
[
fo.Sample(
filepath="/path/to/image1.png",
uniqueness=1.0,
ground_truth=fo.Detections(
detections=[
fo.Detection(
label="cat",
bounding_box=[0.1, 0.1, 0.5, 0.5],
mood="surly",
age=51,
),
fo.Detection(
label="dog",
bounding_box=[0.2, 0.2, 0.3, 0.3],
mood="happy",
age=52,
),
]
)
),
fo.Sample(
filepath="/path/to/image2.png",
uniqueness=0.0,
),
fo.Sample(
filepath="/path/to/image3.png",
),
]
)
#
# Include only the default fields on each sample
#
stage = fo.SelectFields()
view = dataset.add_stage(stage)
#
# Include only the `uniqueness` field (and the default fields) on each
# sample
#
stage = fo.SelectFields("uniqueness")
view = dataset.add_stage(stage)
#
# Include only the `mood` attribute (and the default attributes) of
# each `Detection` in the `ground_truth` field
#
stage = fo.SelectFields("ground_truth.detections.mood")
view = dataset.add_stage(stage)
```
* **Parameters:**
* **field_names** (*None*) – a field name or iterable of field names to select.
May contain `embedded.field.name` as well
* **meta_filter** (*None*) –
a filter that dynamically selects fields in
the collection’s schema according to the specified rule, which
can be matched against the field’s `name`, `type`,
`description`, and/or `info`. For example:
- Use `meta_filter="2023"` or `meta_filter={"any": "2023"}`
to select fields that have the string “2023” anywhere in their
name, type, description, or info
- Use `meta_filter={"type": "StringField"}` or
`meta_filter={"type": "Classification"}` to select all string
or classification fields, respectively
- Use `meta_filter={"description": "my description"}` to
select fields whose description contains the string
“my description”
- Use `meta_filter={"info": "2023"}` to select fields that
have the string “2023” anywhere in their info
- Use `meta_filter={"info.key": "value"}}` to select
fields that have a specific key/value pair in their info
- Include `meta_filter={"include_nested_fields": True, ...}` in
your meta filter to include all nested fields in the filter
**Attributes:**
| [`field_names`](#fiftyone.core.stages.SelectFields.field_names) | A list of field names to select. |
|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`meta_filter`](#fiftyone.core.stages.SelectFields.meta_filter) | A filter that dynamically selects fields. |
| [`flattens_groups`](#fiftyone.core.stages.SelectFields.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.SelectFields.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.SelectFields.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.SelectFields.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.SelectFields.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`get_selected_fields`](#fiftyone.core.stages.SelectFields.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
|----------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`to_mongo`](#fiftyone.core.stages.SelectFields.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
| [`validate`](#fiftyone.core.stages.SelectFields.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_edited_fields`](#fiftyone.core.stages.SelectFields.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.SelectFields.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.SelectFields.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.SelectFields.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.SelectFields.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.SelectFields.get_media_type)(sample_collection) | 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. |
| [`load_view`](#fiftyone.core.stages.SelectFields.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* field_names
A list of field names to select.
#### *property* meta_filter
A filter that dynamically selects fields.
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.SelectFields.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.SelectFields.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.SelectFields.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.SelectFields.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.SelectFields.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
### *class* fiftyone.core.stages.SelectFrames(frame_ids, omit_empty=True)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Selects the frames with the given IDs from a video collection.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("quickstart-video")
#
# Select some specific frames
#
frame_ids = [
dataset.first().frames.first().id,
dataset.last().frames.last().id,
]
stage = fo.SelectFrames(frame_ids)
view = dataset.add_stage(stage)
print(dataset.count())
print(view.count())
print(dataset.count("frames"))
print(view.count("frames"))
```
* **Parameters:**
* **frame_ids** –
the frames to select. Can be any of the following:
- a frame ID
- an iterable of frame IDs
- a [`fiftyone.core.frame.Frame`](fiftyone.core.frame.md#fiftyone.core.frame.Frame) or
[`fiftyone.core.frame.FrameView`](fiftyone.core.frame.md#fiftyone.core.frame.FrameView)
- an iterable of [`fiftyone.core.frame.Frame`](fiftyone.core.frame.md#fiftyone.core.frame.Frame) or
[`fiftyone.core.frame.FrameView`](fiftyone.core.frame.md#fiftyone.core.frame.FrameView) instances
- a [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) whose
frames to select
* **omit_empty** (*True*) – whether to omit samples that have no frames after
selecting the specified frames
**Attributes:**
| [`frame_ids`](#fiftyone.core.stages.SelectFrames.frame_ids) | The list of frame IDs to select. |
|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`omit_empty`](#fiftyone.core.stages.SelectFrames.omit_empty) | Whether to omit samples that have no labels after filtering. |
| [`flattens_groups`](#fiftyone.core.stages.SelectFrames.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.SelectFrames.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.SelectFrames.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.SelectFrames.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.SelectFrames.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.SelectFrames.to_mongo)(_) | Returns the MongoDB aggregation pipeline for the stage. |
|--------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`validate`](#fiftyone.core.stages.SelectFrames.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_edited_fields`](#fiftyone.core.stages.SelectFrames.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.SelectFrames.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.SelectFrames.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.SelectFrames.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.SelectFrames.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.SelectFrames.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.SelectFrames.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.SelectFrames.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* frame_ids
The list of frame IDs to select.
#### *property* omit_empty
Whether to omit samples that have no labels after filtering.
#### to_mongo(\_)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.SelectFrames.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.SelectFrames.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.SelectFrames.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.SelectFrames.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.SelectFrames.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
### *class* fiftyone.core.stages.SelectGroups(group_ids, ordered=False)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Selects the groups with the given IDs from a grouped collection.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("quickstart-groups")
#
# Select some specific groups by ID
#
group_ids = dataset.take(10).values("group.id")
stage = fo.SelectGroups(group_ids)
view = dataset.add_stage(stage)
assert set(view.values("group.id")) == set(group_ids)
stage = fo.SelectGroups(group_ids, ordered=True)
view = dataset.add_stage(stage)
assert view.values("group.id") == group_ids
```
* **Parameters:**
* **groups_ids** –
the groups to select. Can be any of the following:
- a group ID
- an iterable of group IDs
- a [`fiftyone.core.sample.Sample`](fiftyone.core.sample.md#fiftyone.core.sample.Sample) or
[`fiftyone.core.sample.SampleView`](fiftyone.core.sample.md#fiftyone.core.sample.SampleView)
- a group dict returned by
[`get_group()`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection.get_group)
- an iterable of [`fiftyone.core.sample.Sample`](fiftyone.core.sample.md#fiftyone.core.sample.Sample) or
[`fiftyone.core.sample.SampleView`](fiftyone.core.sample.md#fiftyone.core.sample.SampleView) instances
- an iterable of group dicts returned by
[`get_group()`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection.get_group)
- a [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **ordered** (*False*) – whether to sort the groups in the returned view to
match the order of the provided IDs
**Attributes:**
| [`group_ids`](#fiftyone.core.stages.SelectGroups.group_ids) | The list of group IDs to select. |
|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`ordered`](#fiftyone.core.stages.SelectGroups.ordered) | Whether to sort the groups in the same order as the IDs. |
| [`flattens_groups`](#fiftyone.core.stages.SelectGroups.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.SelectGroups.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.SelectGroups.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.SelectGroups.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.SelectGroups.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.SelectGroups.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
|--------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`validate`](#fiftyone.core.stages.SelectGroups.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_edited_fields`](#fiftyone.core.stages.SelectGroups.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.SelectGroups.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.SelectGroups.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.SelectGroups.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.SelectGroups.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.SelectGroups.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.SelectGroups.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.SelectGroups.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* group_ids
The list of group IDs to select.
#### *property* ordered
Whether to sort the groups in the same order as the IDs.
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.SelectGroups.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.SelectGroups.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.SelectGroups.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.SelectGroups.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.SelectGroups.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
### *class* fiftyone.core.stages.SelectLabels(labels=None, ids=None, instance_ids=None, tags=None, fields=None, omit_empty=True)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Selects only the specified labels from a collection.
The returned view will omit samples, sample fields, and individual labels
that do not match the specified selection criteria.
You can perform a selection via one or more of the following methods:
- Provide the `labels` argument, which should contain a list of dicts
in the format returned by
[`fiftyone.core.session.Session.selected_labels`](fiftyone.core.session.md#fiftyone.core.session.Session.selected_labels), to select
specific labels
- Provide the `ids` argument to select labels with specific IDs
- Provide the `instance_ids` argument to select labels with specific
instance IDs
- Provide the `tags` argument to select labels with specific tags
If multiple criteria are specified, labels must match all of them in order
to be selected.
By default, the selection is applied to all
[`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) fields, but you can provide the
`fields` argument to explicitly define the field(s) in which to select.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("quickstart")
#
# Only include the labels currently selected in the App
#
session = fo.launch_app(dataset)
# Select some labels in the App...
stage = fo.SelectLabels(labels=session.selected_labels)
view = dataset.add_stage(stage)
#
# Only include labels with the specified IDs
#
# Grab some label IDs
ids = [
dataset.first().ground_truth.detections[0].id,
dataset.last().predictions.detections[0].id,
]
stage = fo.SelectLabels(ids=ids)
view = dataset.add_stage(stage)
print(view.count("ground_truth.detections"))
print(view.count("predictions.detections"))
#
# Only include labels with the specified tags
#
# Grab some label IDs
ids = [
dataset.first().ground_truth.detections[0].id,
dataset.last().predictions.detections[0].id,
]
# Give the labels a "test" tag
dataset = dataset.clone() # create copy since we're modifying data
dataset.select_labels(ids=ids).tag_labels("test")
print(dataset.count_values("ground_truth.detections.tags"))
print(dataset.count_values("predictions.detections.tags"))
# Retrieve the labels via their tag
stage = fo.SelectLabels(tags="test")
view = dataset.add_stage(stage)
print(view.count("ground_truth.detections"))
print(view.count("predictions.detections"))
```
* **Parameters:**
* **labels** (*None*) – a list of dicts specifying the labels to select in the
format returned by
[`fiftyone.core.session.Session.selected_labels`](fiftyone.core.session.md#fiftyone.core.session.Session.selected_labels)
* **ids** (*None*) – an ID or iterable of IDs of the labels to select
* **instance_ids** (*None*) – an instance ID or iterable of instance IDs of the
labels to select
* **tags** (*None*) – a tag or iterable of tags of labels to select
* **fields** (*None*) – a field or iterable of fields from which to select
* **omit_empty** (*True*) – whether to omit samples that have no labels after
filtering
**Attributes:**
| [`labels`](#fiftyone.core.stages.SelectLabels.labels) | A list of dicts specifying the labels to select. |
|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`ids`](#fiftyone.core.stages.SelectLabels.ids) | A list of IDs of labels to select. |
| [`instance_ids`](#fiftyone.core.stages.SelectLabels.instance_ids) | A list of instance IDs of labels to select. |
| [`tags`](#fiftyone.core.stages.SelectLabels.tags) | A list of tags of labels to select. |
| [`fields`](#fiftyone.core.stages.SelectLabels.fields) | A list of fields from which labels are being selected. |
| [`omit_empty`](#fiftyone.core.stages.SelectLabels.omit_empty) | Whether to omit samples that have no labels after filtering. |
| [`flattens_groups`](#fiftyone.core.stages.SelectLabels.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.SelectLabels.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.SelectLabels.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.SelectLabels.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.SelectLabels.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`get_edited_fields`](#fiftyone.core.stages.SelectLabels.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
|--------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_filtered_fields`](#fiftyone.core.stages.SelectLabels.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`to_mongo`](#fiftyone.core.stages.SelectLabels.to_mongo)(_) | Returns the MongoDB aggregation pipeline for the stage. |
| [`validate`](#fiftyone.core.stages.SelectLabels.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_excluded_fields`](#fiftyone.core.stages.SelectLabels.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.SelectLabels.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.SelectLabels.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.SelectLabels.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.SelectLabels.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.SelectLabels.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* labels
A list of dicts specifying the labels to select.
#### *property* ids
A list of IDs of labels to select.
#### *property* instance_ids
A list of instance IDs of labels to select.
#### *property* tags
A list of tags of labels to select.
#### *property* fields
A list of fields from which labels are being selected.
#### *property* omit_empty
Whether to omit samples that have no labels after filtering.
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### to_mongo(\_)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.SelectLabels.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.SelectLabels.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.SelectLabels.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.SelectLabels.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.SelectLabels.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
### *class* fiftyone.core.stages.Shuffle(seed=None, \_randint=None)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Randomly shuffles the samples in a collection.
Examples:
```default
import fiftyone as fo
dataset = fo.Dataset()
dataset.add_samples(
[
fo.Sample(
filepath="/path/to/image1.png",
ground_truth=fo.Classification(label="cat"),
),
fo.Sample(
filepath="/path/to/image2.png",
ground_truth=fo.Classification(label="dog"),
),
fo.Sample(
filepath="/path/to/image3.png",
ground_truth=None,
),
]
)
#
# Return a view that contains a randomly shuffled version of the
# samples in the dataset
#
stage = fo.Shuffle()
view = dataset.add_stage(stage)
#
# Shuffle the samples with a fixed random seed
#
stage = fo.Shuffle(seed=51)
view = dataset.add_stage(stage)
```
* **Parameters:**
**seed** (*None*) – an optional random seed to use when shuffling the samples
**Attributes:**
| [`seed`](#fiftyone.core.stages.Shuffle.seed) | The random seed to use, or `None`. |
|----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`flattens_groups`](#fiftyone.core.stages.Shuffle.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.Shuffle.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.Shuffle.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.Shuffle.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.Shuffle.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.Shuffle.to_mongo)(_) | Returns the MongoDB aggregation pipeline for the stage. |
|---------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_edited_fields`](#fiftyone.core.stages.Shuffle.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.Shuffle.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.Shuffle.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.Shuffle.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.Shuffle.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.Shuffle.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.Shuffle.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.Shuffle.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
| [`validate`](#fiftyone.core.stages.Shuffle.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
#### *property* seed
The random seed to use, or `None`.
#### to_mongo(\_)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.Shuffle.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.Shuffle.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.Shuffle.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.Shuffle.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.Shuffle.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
### *class* fiftyone.core.stages.Skip(skip)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Omits the given number of samples from the head of a collection.
Examples:
```default
import fiftyone as fo
dataset = fo.Dataset()
dataset.add_samples(
[
fo.Sample(
filepath="/path/to/image1.png",
ground_truth=fo.Classification(label="cat"),
),
fo.Sample(
filepath="/path/to/image2.png",
ground_truth=fo.Classification(label="dog"),
),
fo.Sample(
filepath="/path/to/image3.png",
ground_truth=fo.Classification(label="rabbit"),
),
fo.Sample(
filepath="/path/to/image4.png",
ground_truth=None,
),
]
)
#
# Omit the first two samples from the dataset
#
stage = fo.Skip(2)
view = dataset.add_stage(stage)
```
* **Parameters:**
**skip** – the number of samples to skip. If a non-positive number is
provided, no samples are omitted
**Attributes:**
| [`skip`](#fiftyone.core.stages.Skip.skip) | The number of samples to skip. |
|-------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`flattens_groups`](#fiftyone.core.stages.Skip.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.Skip.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.Skip.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.Skip.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.Skip.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.Skip.to_mongo)(_) | Returns the MongoDB aggregation pipeline for the stage. |
|------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_edited_fields`](#fiftyone.core.stages.Skip.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.Skip.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.Skip.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.Skip.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.Skip.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.Skip.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.Skip.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.Skip.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
| [`validate`](#fiftyone.core.stages.Skip.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
#### *property* skip
The number of samples to skip.
#### to_mongo(\_)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.Skip.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.Skip.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.Skip.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.Skip.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.Skip.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
### *class* fiftyone.core.stages.SortBy(field_or_expr, reverse=False, create_index=False)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Sorts the samples in a collection by the given field(s) or
expression(s).
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
#
# Sort the samples by their `uniqueness` field in ascending order
#
stage = fo.SortBy("uniqueness", reverse=False)
view = dataset.add_stage(stage)
#
# Sorts the samples in descending order by the number of detections in
# their `predictions` field whose bounding box area is less than 0.2
#
# Bboxes are in [top-left-x, top-left-y, width, height] format
bbox = F("bounding_box")
bbox_area = bbox[2] * bbox[3]
small_boxes = F("predictions.detections").filter(bbox_area < 0.2)
stage = fo.SortBy(small_boxes.length(), reverse=True)
view = dataset.add_stage(stage)
#
# Performs a compound sort where samples are first sorted in descending
# order by number of detections and then in ascending order of
# uniqueness for samples with the same number of predictions
#
stage = fo.SortBy(
[
(F("predictions.detections").length(), -1),
("uniqueness", 1),
]
)
view = dataset.add_stage(stage)
num_objects, uniqueness = view[:5].values(
[F("predictions.detections").length(), "uniqueness"]
)
print(list(zip(num_objects, uniqueness)))
```
* **Parameters:**
* **field_or_expr** –
the field(s) or expression(s) to sort by. This can be
any of the following:
- a field to sort by
- an `embedded.field.name` to sort by
- a [`fiftyone.core.expressions.ViewExpression`](fiftyone.core.expressions.md#fiftyone.core.expressions.ViewExpression) or a
[MongoDB aggregation expression](https://docs.mongodb.com/manual/meta/aggregation-quick-reference/#aggregation-expressions)
that defines the quantity to sort by
- a list of `(field_or_expr, order)` tuples defining a compound
sort criteria, where `field_or_expr` is a field or expression
as defined above, and `order` can be 1 or any string starting
with “a” for ascending order, or -1 or any string starting with
“d” for descending order
* **reverse** (*False*) – whether to return the results in descending order
* **create_index** (*False*) – whether to create an index, if necessary, to
optimize the sort. Only applicable when sorting by field(s), not
expressions
**Attributes:**
| [`field_or_expr`](#fiftyone.core.stages.SortBy.field_or_expr) | The field or expression to sort by. |
|---------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`reverse`](#fiftyone.core.stages.SortBy.reverse) | Whether to return the results in descending order. |
| [`create_index`](#fiftyone.core.stages.SortBy.create_index) | Whether to create an index, if necessary, to optimize the sort. |
| [`flattens_groups`](#fiftyone.core.stages.SortBy.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.SortBy.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.SortBy.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.SortBy.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.SortBy.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.SortBy.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
|--------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`validate`](#fiftyone.core.stages.SortBy.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_edited_fields`](#fiftyone.core.stages.SortBy.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.SortBy.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.SortBy.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.SortBy.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.SortBy.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.SortBy.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.SortBy.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.SortBy.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* field_or_expr
The field or expression to sort by.
#### *property* reverse
Whether to return the results in descending order.
#### *property* create_index
Whether to create an index, if necessary, to optimize the sort.
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.SortBy.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.SortBy.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.SortBy.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.SortBy.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.SortBy.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
### *class* fiftyone.core.stages.SortBySimilarity(query, k=None, reverse=False, dist_field=None, brain_key=None, \_state=None)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Sorts a collection by similarity to a specified query.
In order to use this stage, you must first use
[`fiftyone.brain.compute_similarity()`](fiftyone.brain.md#fiftyone.brain.compute_similarity) to index your dataset by
similarity.
Examples:
```default
import fiftyone as fo
import fiftyone.brain as fob
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("quickstart")
fob.compute_similarity(
dataset, model="clip-vit-base32-torch", brain_key="clip"
)
#
# Sort samples by their similarity to a sample by its ID
#
query_id = dataset.first().id
stage = fo.SortBySimilarity(query_id, k=5)
view = dataset.add_stage(stage)
#
# Sort samples by their similarity to a manually computed vector
#
model = foz.load_zoo_model("clip-vit-base32-torch")
embeddings = dataset.take(2, seed=51).compute_embeddings(model)
query = embeddings.mean(axis=0)
stage = fo.SortBySimilarity(query, k=5)
view = dataset.add_stage(stage)
#
# Sort samples by their similarity to a text prompt
#
query = "kites high in the air"
stage = fo.SortBySimilarity(query, k=5)
view = dataset.add_stage(stage)
```
* **Parameters:**
* **query** –
the query, which can be any of the following:
- an ID or iterable of IDs
- a `num_dims` vector or `num_queries x num_dims` array of
vectors
- a prompt or iterable of prompts (if supported by the index)
* **k** (*None*) – the number of matches to return. By default, the entire
collection is sorted
* **reverse** (*False*) – whether to sort by least similarity (True) or greatest
similarity (False). Some backends may not support least similarity
* **dist_field** (*None*) – the name of a float field in which to store the
distance of each example to the specified query. The field is
created if necessary
* **brain_key** (*None*) – the brain key of an existing
[`fiftyone.brain.compute_similarity()`](fiftyone.brain.md#fiftyone.brain.compute_similarity) run on the dataset. If
not specified, the dataset must have an applicable run, which will
be used by default
**Attributes:**
| [`query`](#fiftyone.core.stages.SortBySimilarity.query) | The query. |
|-------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`k`](#fiftyone.core.stages.SortBySimilarity.k) | The number of matches to return. |
| [`reverse`](#fiftyone.core.stages.SortBySimilarity.reverse) | Whether to sort by least similarity. |
| [`dist_field`](#fiftyone.core.stages.SortBySimilarity.dist_field) | The field to store similarity distances, if any. |
| [`brain_key`](#fiftyone.core.stages.SortBySimilarity.brain_key) | The brain key of the similarity index to use. |
| [`flattens_groups`](#fiftyone.core.stages.SortBySimilarity.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.SortBySimilarity.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.SortBySimilarity.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.SortBySimilarity.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.SortBySimilarity.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.SortBySimilarity.to_mongo)(_) | Returns the MongoDB aggregation pipeline for the stage. |
|------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`validate`](#fiftyone.core.stages.SortBySimilarity.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
| [`get_edited_fields`](#fiftyone.core.stages.SortBySimilarity.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.SortBySimilarity.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.SortBySimilarity.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.SortBySimilarity.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.SortBySimilarity.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.SortBySimilarity.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.SortBySimilarity.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.SortBySimilarity.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
#### *property* query
The query.
#### *property* k
The number of matches to return.
#### *property* reverse
Whether to sort by least similarity.
#### *property* dist_field
The field to store similarity distances, if any.
#### *property* brain_key
The brain key of the similarity index to use.
#### to_mongo(\_)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.SortBySimilarity.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.SortBySimilarity.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.SortBySimilarity.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.SortBySimilarity.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.SortBySimilarity.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
### *class* fiftyone.core.stages.Take(size, seed=None, \_randint=None)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Randomly samples the given number of samples from a collection.
Examples:
```default
import fiftyone as fo
dataset = fo.Dataset()
dataset.add_samples(
[
fo.Sample(
filepath="/path/to/image1.png",
ground_truth=fo.Classification(label="cat"),
),
fo.Sample(
filepath="/path/to/image2.png",
ground_truth=fo.Classification(label="dog"),
),
fo.Sample(
filepath="/path/to/image3.png",
ground_truth=fo.Classification(label="rabbit"),
),
fo.Sample(
filepath="/path/to/image4.png",
ground_truth=None,
),
]
)
#
# Take two random samples from the dataset
#
stage = fo.Take(2)
view = dataset.add_stage(stage)
#
# Take two random samples from the dataset with a fixed seed
#
stage = fo.Take(2, seed=51)
view = dataset.add_stage(stage)
```
* **Parameters:**
* **size** – the number of samples to return. If a non-positive number is
provided, an empty view is returned
* **seed** (*None*) – an optional random seed to use when selecting the samples
**Attributes:**
| [`size`](#fiftyone.core.stages.Take.size) | The number of samples to return. |
|-------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`seed`](#fiftyone.core.stages.Take.seed) | The random seed to use, or `None`. |
| [`flattens_groups`](#fiftyone.core.stages.Take.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`has_view`](#fiftyone.core.stages.Take.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.Take.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.Take.to_mongo). |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.Take.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`to_mongo`](#fiftyone.core.stages.Take.to_mongo)(_) | Returns the MongoDB aggregation pipeline for the stage. |
|------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_edited_fields`](#fiftyone.core.stages.Take.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.Take.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.Take.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.Take.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.Take.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.Take.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.Take.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`load_view`](#fiftyone.core.stages.Take.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
| [`validate`](#fiftyone.core.stages.Take.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
#### *property* size
The number of samples to return.
#### *property* seed
The random seed to use, or `None`.
#### to_mongo(\_)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.Take.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.Take.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.Take.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.Take.to_mongo).
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.Take.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
### *class* fiftyone.core.stages.ToPatches(field, config=None, \_state=None, \*\*kwargs)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Creates a view that contains one sample per object patch in the
specified field of a collection.
A `sample_id` field will be added that records the sample ID from which
each patch was taken.
By default, fields other than `field` and the default sample fields will
not be included in the returned view.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("quickstart")
session = fo.launch_app(dataset)
#
# Create a view containing the ground truth patches
#
stage = fo.ToPatches("ground_truth")
view = dataset.add_stage(stage)
print(view)
session.view = view
```
* **Parameters:**
* **field** – the patches field, which must be of type
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections),
[`fiftyone.core.labels.Polylines`](fiftyone.core.labels.md#fiftyone.core.labels.Polylines), or
[`fiftyone.core.labels.Keypoints`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoints)
* **config** (*None*) – an optional dict of keyword arguments for
[`fiftyone.core.patches.make_patches_dataset()`](fiftyone.core.patches.md#fiftyone.core.patches.make_patches_dataset) specifying how
to perform the conversion
* **\*\*kwargs** – optional keyword arguments for
[`fiftyone.core.patches.make_patches_dataset()`](fiftyone.core.patches.md#fiftyone.core.patches.make_patches_dataset) specifying how
to perform the conversion
**Attributes:**
| [`has_view`](#fiftyone.core.stages.ToPatches.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.ToPatches.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.ToPatches.to_mongo). |
|------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`field`](#fiftyone.core.stages.ToPatches.field) | The patches field. |
| [`config`](#fiftyone.core.stages.ToPatches.config) | Parameters specifying how to perform the conversion. |
| [`flattens_groups`](#fiftyone.core.stages.ToPatches.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.ToPatches.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`load_view`](#fiftyone.core.stages.ToPatches.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
|-----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_edited_fields`](#fiftyone.core.stages.ToPatches.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.ToPatches.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.ToPatches.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.ToPatches.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.ToPatches.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.ToPatches.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.ToPatches.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`to_mongo`](#fiftyone.core.stages.ToPatches.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
| [`validate`](#fiftyone.core.stages.ToPatches.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.ToPatches.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.ToPatches.to_mongo).
#### *property* field
The patches field.
#### *property* config
Parameters specifying how to perform the conversion.
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ToPatches.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.ToPatches.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ToPatches.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
### *class* fiftyone.core.stages.ToEvaluationPatches(eval_key, config=None, \_state=None, \*\*kwargs)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Creates a view based on the results of the evaluation with the given key
that contains one sample for each true positive, false positive, and false
negative example in the collection, respectively.
True positive examples will result in samples with both their ground truth
and predicted fields populated, while false positive/negative examples wilL
only have one of their corresponding predicted/ground truth fields
populated, respectively.
If multiple predictions are matched to a ground truth object (e.g., if the
evaluation protocol includes a crowd attribute), then all matched
predictions will be stored in the single sample along with the ground truth
object.
The returned dataset will also have top-level `type` and `iou` fields
populated based on the evaluation results for that example, as well as a
`sample_id` field recording the sample ID of the example, and a `crowd`
field if the evaluation protocol defines a crowd attribute.
#### NOTE
The returned view will contain patches for the contents of this
collection, which may differ from the view on which the `eval_key`
evaluation was performed. This may exclude some labels that were
evaluated and/or include labels that were not evaluated.
If you would like to see patches for the exact view on which an
evaluation was performed, first call
[`load_evaluation_view()`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection.load_evaluation_view)
to load the view and then convert to patches.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("quickstart")
dataset.evaluate_detections("predictions", eval_key="eval")
session = fo.launch_app(dataset)
#
# Create a patches view for the evaluation results
#
stage = fo.ToEvaluationPatches("eval")
view = dataset.add_stage(stage)
print(view)
session.view = view
```
* **Parameters:**
* **eval_key** – an evaluation key that corresponds to the evaluation of
ground truth/predicted fields that are of type
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections),
`fiftyone.core.labels.Polylines, or
:class:`fiftyone.core.labels.Keypoints`
* **config** (*None*) – an optional dict of keyword arguments for
[`fiftyone.core.patches.make_evaluation_patches_dataset()`](fiftyone.core.patches.md#fiftyone.core.patches.make_evaluation_patches_dataset)
specifying how to perform the conversion
* **\*\*kwargs** – optional keyword arguments for
[`fiftyone.core.patches.make_evaluation_patches_dataset()`](fiftyone.core.patches.md#fiftyone.core.patches.make_evaluation_patches_dataset)
specifying how to perform the conversion
**Attributes:**
| [`has_view`](#fiftyone.core.stages.ToEvaluationPatches.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.ToEvaluationPatches.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.ToEvaluationPatches.to_mongo). |
|----------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`eval_key`](#fiftyone.core.stages.ToEvaluationPatches.eval_key) | The evaluation key to extract patches for. |
| [`config`](#fiftyone.core.stages.ToEvaluationPatches.config) | Parameters specifying how to perform the conversion. |
| [`flattens_groups`](#fiftyone.core.stages.ToEvaluationPatches.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.ToEvaluationPatches.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`load_view`](#fiftyone.core.stages.ToEvaluationPatches.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
|---------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_edited_fields`](#fiftyone.core.stages.ToEvaluationPatches.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.ToEvaluationPatches.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.ToEvaluationPatches.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.ToEvaluationPatches.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.ToEvaluationPatches.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.ToEvaluationPatches.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.ToEvaluationPatches.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`to_mongo`](#fiftyone.core.stages.ToEvaluationPatches.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
| [`validate`](#fiftyone.core.stages.ToEvaluationPatches.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.ToEvaluationPatches.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.ToEvaluationPatches.to_mongo).
#### *property* eval_key
The evaluation key to extract patches for.
#### *property* config
Parameters specifying how to perform the conversion.
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ToEvaluationPatches.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.ToEvaluationPatches.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ToEvaluationPatches.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
### *class* fiftyone.core.stages.ToClips(field_or_expr, config=None, \_state=None, \*\*kwargs)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Creates a view that contains one sample per clip defined by the given
field or expression in a video collection.
The returned view will contain:
- A `sample_id` field that records the sample ID from which each clip
was taken
- A `support` field that records the `[first, last]` frame support of
each clip
- All frame-level information from the underlying dataset of the input
collection
Refer to [`fiftyone.core.clips.make_clips_dataset()`](fiftyone.core.clips.md#fiftyone.core.clips.make_clips_dataset) to see the
available configuration options for generating clips.
#### NOTE
The clip generation logic will respect any frame-level modifications
defined in the input collection, but the output clips will always
contain all frame-level labels.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart-video")
#
# Create a clips view that contains one clip for each contiguous
# segment that contains at least one road sign in every frame
#
stage1 = fo.FilterLabels("frames.detections", F("label") == "road sign")
stage2 = fo.ToClips("frames.detections")
clips = dataset.add_stage(stage1).add_stage(stage2)
print(clips)
#
# Create a clips view that contains one clip for each contiguous
# segment that contains at least two road signs in every frame
#
signs = F("detections.detections").filter(F("label") == "road sign")
stage = fo.ToClips(signs.length() >= 2)
clips = dataset.add_stage(stage)
print(clips)
```
* **Parameters:**
* **field_or_expr** –
can be any of the following:
- a [`fiftyone.core.labels.TemporalDetection`](fiftyone.core.labels.md#fiftyone.core.labels.TemporalDetection),
[`fiftyone.core.labels.TemporalDetections`](fiftyone.core.labels.md#fiftyone.core.labels.TemporalDetections),
[`fiftyone.core.fields.FrameSupportField`](fiftyone.core.fields.md#fiftyone.core.fields.FrameSupportField), or list of
[`fiftyone.core.fields.FrameSupportField`](fiftyone.core.fields.md#fiftyone.core.fields.FrameSupportField) field
- a frame-level label list field of any of the following types:
- [`fiftyone.core.labels.Classifications`](fiftyone.core.labels.md#fiftyone.core.labels.Classifications)
- [`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections)
- [`fiftyone.core.labels.Polylines`](fiftyone.core.labels.md#fiftyone.core.labels.Polylines)
- [`fiftyone.core.labels.Keypoints`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoints)
- a [`fiftyone.core.expressions.ViewExpression`](fiftyone.core.expressions.md#fiftyone.core.expressions.ViewExpression) that
returns a boolean to apply to each frame of the input
collection to determine if the frame should be clipped
- a list of `[(first1, last1), (first2, last2), ...]` lists
defining the frame numbers of the clips to extract from each
sample
* **config** (*None*) – an optional dict of keyword arguments for
[`fiftyone.core.clips.make_clips_dataset()`](fiftyone.core.clips.md#fiftyone.core.clips.make_clips_dataset) specifying how to
perform the conversion
* **\*\*kwargs** – optional keyword arguments for
[`fiftyone.core.clips.make_clips_dataset()`](fiftyone.core.clips.md#fiftyone.core.clips.make_clips_dataset) specifying how to
perform the conversion
**Attributes:**
| [`has_view`](#fiftyone.core.stages.ToClips.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.ToClips.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.ToClips.to_mongo). |
|----------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`field_or_expr`](#fiftyone.core.stages.ToClips.field_or_expr) | The field or expression defining how to extract the clips. |
| [`config`](#fiftyone.core.stages.ToClips.config) | Parameters specifying how to perform the conversion. |
| [`flattens_groups`](#fiftyone.core.stages.ToClips.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.ToClips.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`load_view`](#fiftyone.core.stages.ToClips.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
|---------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_edited_fields`](#fiftyone.core.stages.ToClips.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.ToClips.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.ToClips.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.ToClips.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.ToClips.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.ToClips.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.ToClips.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`to_mongo`](#fiftyone.core.stages.ToClips.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
| [`validate`](#fiftyone.core.stages.ToClips.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.ToClips.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.ToClips.to_mongo).
#### *property* field_or_expr
The field or expression defining how to extract the clips.
#### *property* config
Parameters specifying how to perform the conversion.
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ToClips.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.ToClips.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ToClips.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
### *class* fiftyone.core.stages.ToTrajectories(field, config=None, \_state=None, \*\*kwargs)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Creates a view that contains one clip for each unique object trajectory
defined by their `(label, index)` in a frame-level field of a video
collection.
The returned view will contain:
- A `sample_id` field that records the sample ID from which each clip
was taken
- A `support` field that records the `[first, last]` frame support of
each clip
- A sample-level label field that records the `label` and `index` of
each trajectory
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart-video")
#
# Create a trajectories view for the vehicles in the dataset
#
stage1 = fo.FilterLabels("frames.detections", F("label") == "vehicle")
stage2 = fo.ToTrajectories("frames.detections")
trajectories = dataset.add_stage(stage1).add_stage(stage2)
print(trajectories)
```
* **Parameters:**
* **field** –
a frame-level label list field of any of the following types:
- [`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections)
- [`fiftyone.core.labels.Polylines`](fiftyone.core.labels.md#fiftyone.core.labels.Polylines)
- [`fiftyone.core.labels.Keypoints`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoints)
* **config** (*None*) – an optional dict of keyword arguments for
[`fiftyone.core.clips.make_clips_dataset()`](fiftyone.core.clips.md#fiftyone.core.clips.make_clips_dataset) specifying how to
perform the conversion
* **\*\*kwargs** – optional keyword arguments for
[`fiftyone.core.clips.make_clips_dataset()`](fiftyone.core.clips.md#fiftyone.core.clips.make_clips_dataset) specifying how to
perform the conversion
**Attributes:**
| [`has_view`](#fiftyone.core.stages.ToTrajectories.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.ToTrajectories.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.ToTrajectories.to_mongo). |
|-----------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`field`](#fiftyone.core.stages.ToTrajectories.field) | The label field for which to extract trajectories. |
| [`config`](#fiftyone.core.stages.ToTrajectories.config) | Parameters specifying how to perform the conversion. |
| [`flattens_groups`](#fiftyone.core.stages.ToTrajectories.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.ToTrajectories.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`load_view`](#fiftyone.core.stages.ToTrajectories.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
|----------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_edited_fields`](#fiftyone.core.stages.ToTrajectories.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.ToTrajectories.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.ToTrajectories.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.ToTrajectories.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.ToTrajectories.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.ToTrajectories.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.ToTrajectories.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`to_mongo`](#fiftyone.core.stages.ToTrajectories.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
| [`validate`](#fiftyone.core.stages.ToTrajectories.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.ToTrajectories.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.ToTrajectories.to_mongo).
#### *property* field
The label field for which to extract trajectories.
#### *property* config
Parameters specifying how to perform the conversion.
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ToTrajectories.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.ToTrajectories.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ToTrajectories.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection
### *class* fiftyone.core.stages.ToFrames(config=None, \_state=None, \*\*kwargs)
Bases: [`ViewStage`](#fiftyone.core.stages.ViewStage)
Creates a view that contains one sample per frame in a video collection.
The returned view will contain all frame-level fields and the `tags` of
each video as sample-level fields, as well as a `sample_id` field that
records the IDs of the parent sample for each frame.
By default, `sample_frames` is False and this method assumes that the
frames of the input collection have `filepath` fields populated pointing
to each frame image. Any frames without a `filepath` populated will be
omitted from the returned view.
When `sample_frames` is True, this method samples each video in the
collection into a directory of per-frame images and stores the filepaths in
the `filepath` frame field of the source dataset. By default, each folder
of images is written using the same basename as the input video. For
example, if `frames_patt = "%%06d.jpg"`, then videos with the following
paths:
```default
/path/to/video1.mp4
/path/to/video2.mp4
...
```
would be sampled as follows:
```default
/path/to/video1/
000001.jpg
000002.jpg
...
/path/to/video2/
000001.jpg
000002.jpg
...
```
However, you can use the optional `output_dir` and `rel_dir` parameters
to customize the location and shape of the sampled frame folders. For
example, if `output_dir = "/tmp"` and `rel_dir = "/path/to"`, then
videos with the following paths:
```default
/path/to/folderA/video1.mp4
/path/to/folderA/video2.mp4
/path/to/folderB/video3.mp4
...
```
would be sampled as follows:
```default
/tmp/folderA/
video1/
000001.jpg
000002.jpg
...
video2/
000001.jpg
000002.jpg
...
/tmp/folderB/
video3/
000001.jpg
000002.jpg
...
```
By default, samples will be generated for every video frame at full
resolution, but this method provides a variety of parameters that can be
used to customize the sampling behavior.
#### NOTE
If this method is run multiple times with `sample_frames` set to
True, existing frames will not be resampled unless you set
`force_sample` to True.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart-video")
session = fo.launch_app(dataset)
#
# Create a frames view for an entire video dataset
#
stage = fo.ToFrames(sample_frames=True)
frames = dataset.add_stage(stage)
print(frames)
session.view = frames
#
# Create a frames view that only contains frames with at least 10
# objects, sampled at a maximum frame rate of 1fps
#
num_objects = F("detections.detections").length()
view = dataset.match_frames(num_objects > 10)
stage = fo.ToFrames(max_fps=1)
frames = view.add_stage(stage)
print(frames)
session.view = frames
```
* **Parameters:**
* **config** (*None*) – an optional dict of keyword arguments for
[`fiftyone.core.video.make_frames_dataset()`](fiftyone.core.video.md#fiftyone.core.video.make_frames_dataset) specifying how to
perform the conversion
* **\*\*kwargs** – optional keyword arguments for
[`fiftyone.core.video.make_frames_dataset()`](fiftyone.core.video.md#fiftyone.core.video.make_frames_dataset) specifying how to
perform the conversion
**Attributes:**
| [`has_view`](#fiftyone.core.stages.ToFrames.has_view) | Whether this stage's output view should be loaded via [`load_view()`](#fiftyone.core.stages.ToFrames.load_view) rather than appending stages to an aggregation pipeline via [`to_mongo()`](#fiftyone.core.stages.ToFrames.to_mongo). |
|-----------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`config`](#fiftyone.core.stages.ToFrames.config) | Parameters specifying how to perform the conversion. |
| [`flattens_groups`](#fiftyone.core.stages.ToFrames.flattens_groups) | Whether this stage flattens groups into a non-grouped collection. |
| [`outputs_dynamic_groups`](#fiftyone.core.stages.ToFrames.outputs_dynamic_groups) | Whether this stage outputs or flattens dynamic groups. |
**Methods:**
| [`load_view`](#fiftyone.core.stages.ToFrames.load_view)(sample_collection[, saved_view, ...]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the output of the stage. |
|----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_edited_fields`](#fiftyone.core.stages.ToFrames.get_edited_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that may have been edited by the stage, if any. |
| [`get_excluded_fields`](#fiftyone.core.stages.ToFrames.get_excluded_fields)(sample_collection[, frames]) | Returns a list of fields that have been excluded by the stage, if any. |
| [`get_filtered_fields`](#fiftyone.core.stages.ToFrames.get_filtered_fields)(sample_collection[, frames]) | Returns a list of names of fields or embedded fields that contain **arrays** have been filtered by the stage, if any. |
| [`get_group_expr`](#fiftyone.core.stages.ToFrames.get_group_expr)(sample_collection) | Returns the dynamic group expression for the given stage, if any. |
| [`get_group_media_types`](#fiftyone.core.stages.ToFrames.get_group_media_types)(sample_collection) | Returns the group media types outputted by this stage, if any, when applied to the given collection, if and only if they are different from the input collection. |
| [`get_media_type`](#fiftyone.core.stages.ToFrames.get_media_type)(sample_collection) | 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. |
| [`get_selected_fields`](#fiftyone.core.stages.ToFrames.get_selected_fields)(sample_collection[, frames]) | Returns a list of fields that have been selected by the stage, if any. |
| [`to_mongo`](#fiftyone.core.stages.ToFrames.to_mongo)(sample_collection) | Returns the MongoDB aggregation pipeline for the stage. |
| [`validate`](#fiftyone.core.stages.ToFrames.validate)(sample_collection) | Validates that the stage can be applied to the given collection. |
#### *property* has_view
Whether this stage’s output view should be loaded via
[`load_view()`](#fiftyone.core.stages.ToFrames.load_view) rather than appending stages to an aggregation
pipeline via [`to_mongo()`](#fiftyone.core.stages.ToFrames.to_mongo).
#### *property* config
Parameters specifying how to perform the conversion.
#### load_view(sample_collection, saved_view=False, reload=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) containing the
output of the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ToFrames.has_view) is `True`.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **saved_view** (*False*) – whether this view stage is being loaded in the
context of loading a saved view
* **reload** (*False*) – whether to force reload generated collections, if
necessary
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* flattens_groups
Whether this stage flattens groups into a non-grouped collection.
The possible return values are:
- `True`: this stage *flattens* groups
- `False`: this stage *does not flatten* groups
- `None`: this stage does not change group status
#### get_edited_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that may have
been edited by the stage, if any.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been edited
#### get_excluded_fields(sample_collection, frames=False)
Returns a list of fields that have been excluded by the stage, if
any.
View stages only need to report excluded fields if they insist that
excluded fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### get_filtered_fields(sample_collection, frames=False)
Returns a list of names of fields or embedded fields that contain
**arrays** have been filtered by the stage, if any.
For example, if a stage filters a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field called
`"predictions"`, it should include `"predictions.detections"` in
the returned list.
The `"frames."` prefix should be omitted when `frames` is True.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been filtered
#### get_group_expr(sample_collection)
Returns the dynamic group expression for the given stage, if any.
Only usable if [`outputs_dynamic_groups()`](#fiftyone.core.stages.ToFrames.outputs_dynamic_groups) is `True`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`
#### get_group_media_types(sample_collection)
Returns the group media types outputted by this stage, if any, when
applied to the given collection, if and only if they are different from
the input collection.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a dict mapping slice names to media types, or `None` if the stage
does not change the types
#### get_media_type(sample_collection)
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`](fiftyone.core.collections.md#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
#### get_selected_fields(sample_collection, frames=False)
Returns a list of fields that have been selected by the stage, if
any.
View stages only need to report selected fields if they insist that
non-selected fields not appear in the schema of the returned view.
* **Parameters:**
* **sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **frames** (*False*) – whether to return sample-level (False) or
frame-level (True) fields
* **Returns:**
a list of fields, or `None` if no fields have been selected
#### *property* outputs_dynamic_groups
Whether this stage outputs or flattens dynamic groups.
The possible return values are:
- `True`: this stage *dynamically groups* the input collection
- `False`: this stage *flattens* dynamic groups
- `None`: this stage does not change group status
#### to_mongo(sample_collection)
Returns the MongoDB aggregation pipeline for the stage.
Only usable if [`has_view()`](#fiftyone.core.stages.ToFrames.has_view) is `False`.
* **Parameters:**
**sample_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to which
the stage is being applied
* **Returns:**
a MongoDB aggregation pipeline (list of dicts)
#### validate(sample_collection)
Validates that the stage can be applied to the given collection.
* **Parameters:**
**sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Raises:**
[**ViewStageError**](#fiftyone.core.stages.ViewStageError) – if the stage cannot be applied to the
collection