# fiftyone.core.clips
Clips views.
Copyright 2017-2026, Voxel51, Inc.
[voxel51.com](https://voxel51.com/)
**Classes:**
| [`ClipView`](#fiftyone.core.clips.ClipView)(doc, view[, selected_fields, ...]) | A clip in a [`ClipsView`](#fiftyone.core.clips.ClipsView). |
|--------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`ClipsView`](#fiftyone.core.clips.ClipsView)(source_collection, clips_stage, ...) | A [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) of clips from a video [`fiftyone.core.dataset.Dataset`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset). |
| [`TrajectoriesView`](#fiftyone.core.clips.TrajectoriesView)(source_collection, ...[, ...]) | A [`ClipsView`](#fiftyone.core.clips.ClipsView) of object trajectories from a video [`fiftyone.core.dataset.Dataset`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset). |
**Functions:**
| [`make_clips_dataset`](#fiftyone.core.clips.make_clips_dataset)(sample_collection, ...[, ...]) | Creates a dataset that contains one sample per clip defined by the given field or expression in the collection. |
|--------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|
### *class* fiftyone.core.clips.ClipView(doc, view, selected_fields=None, excluded_fields=None, filtered_fields=None)
Bases: [`SampleView`](fiftyone.core.sample.md#fiftyone.core.sample.SampleView)
A clip in a [`ClipsView`](#fiftyone.core.clips.ClipsView).
[`ClipView`](#fiftyone.core.clips.ClipView) instances should not be created manually; they are
generated by iterating over [`ClipsView`](#fiftyone.core.clips.ClipsView) instances.
* **Parameters:**
* **doc** – a [`fiftyone.core.odm.DatasetSampleDocument`](fiftyone.core.odm.md#fiftyone.core.odm.DatasetSampleDocument)
* **view** – the [`ClipsView`](#fiftyone.core.clips.ClipsView) that the frame belongs to
* **selected_fields** (*None*) – a set of field names that this view is
restricted to
* **excluded_fields** (*None*) – a set of field names that are excluded from
this view
* **filtered_fields** (*None*) – a set of field names of list fields that are
filtered in this view
**Methods:**
| [`add_labels`](#fiftyone.core.clips.ClipView.add_labels)(labels[, label_field, ...]) | Adds the given labels to the sample. |
|---------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| [`clear_field`](#fiftyone.core.clips.ClipView.clear_field)(field_name) | Clears the value of a field of the document. |
| [`compute_metadata`](#fiftyone.core.clips.ClipView.compute_metadata)([overwrite, skip_failures]) | Populates the `metadata` field of the sample. |
| [`copy`](#fiftyone.core.clips.ClipView.copy)([fields, omit_fields]) | Returns a deep copy of the sample that has not been added to the database. |
| [`get_field`](#fiftyone.core.clips.ClipView.get_field)(field_name) | Gets the value of a field of the document. |
| [`get_media_key`](#fiftyone.core.clips.ClipView.get_media_key)() | Returns the sample's active logical media key. |
| [`has_field`](#fiftyone.core.clips.ClipView.has_field)(field_name) | Determines whether the document has the given field. |
| [`iter_fields`](#fiftyone.core.clips.ClipView.iter_fields)([include_id, include_timestamps]) | Returns an iterator over the `(name, value)` pairs of the public fields of the document. |
| [`merge`](#fiftyone.core.clips.ClipView.merge)(sample[, fields, omit_fields, ...]) | Merges the fields of the given sample into this sample. |
| [`save`](#fiftyone.core.clips.ClipView.save)() | Saves the sample view to the database. |
| [`set_field`](#fiftyone.core.clips.ClipView.set_field)(field_name, value[, create, ...]) | Sets the value of a field of the document. |
| [`to_dict`](#fiftyone.core.clips.ClipView.to_dict)([include_frames, include_private]) | Serializes the sample view to a JSON dictionary. |
| [`to_json`](#fiftyone.core.clips.ClipView.to_json)([pretty_print]) | Serializes the document to a JSON string. |
| [`to_mongo_dict`](#fiftyone.core.clips.ClipView.to_mongo_dict)([include_id]) | Serializes the document to a BSON dictionary equivalent to the representation that would be stored in the database. |
| [`update_fields`](#fiftyone.core.clips.ClipView.update_fields)(fields_dict[, expand_schema, ...]) | Sets the dictionary of fields on the document. |
**Attributes:**
| [`dataset`](#fiftyone.core.clips.ClipView.dataset) | The dataset to which this document belongs, or `None` if it has not been added to a dataset. |
|------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`dataset_id`](#fiftyone.core.clips.ClipView.dataset_id) | |
| [`excluded_field_names`](#fiftyone.core.clips.ClipView.excluded_field_names) | The set of field names that are excluded on this document view, or `None` if no fields are explicitly excluded. |
| [`field_names`](#fiftyone.core.clips.ClipView.field_names) | An ordered tuple of field names of this document view. |
| [`filename`](#fiftyone.core.clips.ClipView.filename) | The basename or logical display name of the sample's media. |
| [`filtered_field_names`](#fiftyone.core.clips.ClipView.filtered_field_names) | The set of field names or `embedded.field.names` that have been filtered on this document view, or `None` if no fields are filtered. |
| [`in_dataset`](#fiftyone.core.clips.ClipView.in_dataset) | Whether the document has been added to a dataset. |
| [`media_reference`](#fiftyone.core.clips.ClipView.media_reference) | The sample's [`fiftyone.core.media_reference.MediaReference`](fiftyone.core.media_reference.md#fiftyone.core.media_reference.MediaReference), or None for a filepath-backed sample. |
| [`media_type`](#fiftyone.core.clips.ClipView.media_type) | The media type of the sample. |
| [`selected_field_names`](#fiftyone.core.clips.ClipView.selected_field_names) | The set of field names that are selected on this document view, or `None` if no fields are explicitly selected. |
#### add_labels(labels, label_field=None, confidence_thresh=None, classes=None, expand_schema=True, validate=True, dynamic=False)
Adds the given labels to the sample.
The provided `labels` can be any of the following:
- A [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) instance, in which case the
labels are directly saved in the specified `label_field`
- A dict mapping keys to [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label)
instances. In this case, the labels are added as follows:
```default
for key, value in labels.items():
sample[label_key(key)] = value
```
- A dict mapping frame numbers to [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label)
instances. In this case, the provided labels are interpreted as
frame-level labels that should be added as follows:
```default
sample.frames.merge(
{
frame_number: {label_field: label}
for frame_number, label in labels.items()
}
)
```
- A dict mapping frame numbers to dicts mapping keys to
[`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) instances. In this case, the
provided labels are interpreted as frame-level labels that should
be added as follows:
```default
sample.frames.merge(
{
frame_number: {
label_key(key): value
for key, value in frame_dict.items()
}
for frame_number, frame_dict in labels.items()
}
)
```
In the above, the `label_key` function maps label dict keys to field
names, and is defined from `label_field` as follows:
```default
if isinstance(label_field, dict):
label_key = lambda k: label_field.get(k, k)
elif label_field is not None:
label_key = lambda k: label_field + "_" + k
else:
label_key = lambda k: k
```
* **Parameters:**
* **labels** – a [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) or dict of labels per
the description above
* **label_field** (*None*) – the sample field, prefix, or dict defining in
which field(s) to save the labels
* **confidence_thresh** (*None*) – an optional confidence threshold to apply
to any applicable labels before saving them
* **classes** (*None*) – an optional iterable of classes to which to
restrict any applicable labels generated by the model
* **expand_schema** (*True*) – whether to dynamically add new fields
encountered to the dataset schema. If False, an error is raised
if any fields are not in the dataset schema
* **validate** (*True*) – whether to validate values for existing fields
* **dynamic** (*False*) – whether to declare dynamic attributes
#### clear_field(field_name)
Clears the value of a field of the document.
* **Parameters:**
**field_name** – the name of the field to clear
* **Raises:**
**AttributeError** – if the field does not exist
#### compute_metadata(overwrite=False, skip_failures=False)
Populates the `metadata` field of the sample.
* **Parameters:**
* **overwrite** (*False*) – whether to overwrite existing metadata
* **skip_failures** (*False*) – whether to gracefully continue without
raising an error if metadata cannot be computed
#### copy(fields=None, omit_fields=None)
Returns a deep copy of the sample that has not been added to the
database.
* **Parameters:**
* **fields** (*None*) – an optional field or iterable of fields to which to
restrict the copy. This can also be a dict mapping existing
field names to new field names
* **omit_fields** (*None*) – an optional field or iterable of fields to
exclude from the copy
* **Returns:**
a `Sample`
#### *property* dataset
The dataset to which this document belongs, or `None` if it has
not been added to a dataset.
#### *property* dataset_id
#### *property* excluded_field_names
The set of field names that are excluded on this document view, or
`None` if no fields are explicitly excluded.
#### *property* field_names
An ordered tuple of field names of this document view.
This may be a subset of all fields of the document if fields have been
selected or excluded.
#### *property* filename
The basename or logical display name of the sample’s media.
#### *property* filtered_field_names
The set of field names or `embedded.field.names` that have been
filtered on this document view, or `None` if no fields are filtered.
#### get_field(field_name)
Gets the value of a field of the document.
* **Parameters:**
**field_name** – the field name
* **Returns:**
the field value
* **Raises:**
**AttributeError** – if the field does not exist
#### get_media_key()
Returns the sample’s active logical media key.
Reference-backed samples return their reference’s key. All other
samples return their filepath.
#### has_field(field_name)
Determines whether the document has the given field.
* **Parameters:**
**field_name** – the field name
* **Returns:**
True/False
#### *property* in_dataset
Whether the document has been added to a dataset.
#### iter_fields(include_id=False, include_timestamps=False)
Returns an iterator over the `(name, value)` pairs of the public
fields of the document.
* **Parameters:**
* **include_id** (*False*) – whether to include the `id` field
* **include_timestamps** (*False*) – whether to include the `created_at`
and `last_modified_at` fields
* **Returns:**
an iterator that emits `(name, value)` tuples
#### *property* media_reference
The sample’s
[`fiftyone.core.media_reference.MediaReference`](fiftyone.core.media_reference.md#fiftyone.core.media_reference.MediaReference), or None for a filepath-backed sample.
The reference says which media source the sample’s media comes from
and where in it the sample is; the source itself is recorded once on
the dataset.
#### *property* media_type
The media type of the sample.
#### merge(sample, fields=None, omit_fields=None, merge_lists=True, merge_embedded_docs=False, overwrite=True, expand_schema=True, validate=True, dynamic=False)
Merges the fields of the given sample into this sample.
The behavior of this method is highly customizable. By default, all
top-level fields from the provided sample are merged in, overwriting
any existing values for those fields, with the exception of list fields
(e.g., `tags`) and label list fields (e.g.,
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) fields), in which case the
elements of the lists themselves are merged. In the case of label list
fields, labels with the same `id` in both samples are updated rather
than duplicated.
To avoid confusion between missing fields and fields whose value is
`None`, `None`-valued fields are always treated as missing while
merging.
This method can be configured in numerous ways, including:
- Whether new fields can be added to the dataset schema
- Whether list fields should be treated as ordinary fields and merged
as a whole rather than merging their elements
- Whether to merge only specific fields, or all but certain fields
- Mapping input sample fields to different field names of this sample
* **Parameters:**
* **sample** – a [`fiftyone.core.sample.Sample`](fiftyone.core.sample.md#fiftyone.core.sample.Sample)
* **fields** (*None*) – an optional field or iterable of fields to which to
restrict the merge. May contain frame fields for video samples.
This can also be a dict mapping field names of the input sample
to field names of this sample
* **omit_fields** (*None*) – an optional field or iterable of fields to
exclude from the merge. May contain frame fields for video
samples
* **merge_lists** (*True*) – whether to merge the elements of list fields
(e.g., `tags`) and label list fields (e.g.,
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) fields) rather than
merging the entire top-level field like other field types.
For label lists fields, existing
`fiftyone.core.label.Label` elements are either replaced
(when `overwrite` is True) or kept (when `overwrite` is
False) when their `id` matches a label from the provided
sample
* **merge_embedded_docs** (*False*) – whether to merge the attributes of
embedded documents (True) rather than merging the entire
top-level field (False)
* **overwrite** (*True*) – whether to overwrite (True) or skip (False)
existing fields and label elements
* **expand_schema** (*True*) – whether to dynamically add new fields
encountered to the dataset schema. If False, an error is raised
if any fields are not in the dataset schema
* **validate** (*True*) – whether to validate values for existing fields
* **dynamic** (*False*) – whether to declare dynamic embedded document
fields
#### save()
Saves the sample view to the database.
#### WARNING
This will permanently delete any omitted or filtered contents from
the source dataset.
#### *property* selected_field_names
The set of field names that are selected on this document view, or
`None` if no fields are explicitly selected.
#### set_field(field_name, value, create=True, validate=True, dynamic=False)
Sets the value of a field of the document.
* **Parameters:**
* **field_name** – the field name
* **value** – the field value
* **create** (*True*) – whether to create the field if it does not exist
* **validate** (*True*) – whether to validate values for existing fields
* **dynamic** (*False*) – whether to declare dynamic embedded document
fields
* **Raises:**
* **ValueError** – if `field_name` is not an allowed field name
* **AttributeError** – if the field does not exist and `create == False`
#### to_dict(include_frames=False, include_private=False)
Serializes the sample view to a JSON dictionary.
* **Parameters:**
* **include_frames** (*False*) – whether to include the frame labels for
video samples
* **include_private** (*False*) – whether to include private fields
* **Returns:**
a JSON dict
#### to_json(pretty_print=False)
Serializes the document to a JSON string.
The document ID and private fields are excluded in this representation.
* **Parameters:**
**pretty_print** (*False*) – whether to render the JSON in human readable
format with newlines and indentations
* **Returns:**
a JSON string
#### to_mongo_dict(include_id=False)
Serializes the document to a BSON dictionary equivalent to the
representation that would be stored in the database.
* **Parameters:**
**include_id** (*False*) – whether to include the document ID
* **Returns:**
a BSON dict
#### update_fields(fields_dict, expand_schema=True, validate=True, dynamic=False)
Sets the dictionary of fields on the document.
* **Parameters:**
* **fields_dict** – a dict mapping field names to values
* **expand_schema** (*True*) – whether to dynamically add new fields
encountered to the document schema. If False, an error is
raised if any fields are not in the document schema
* **validate** (*True*) – whether to validate values for existing fields
* **dynamic** (*False*) – whether to declare dynamic embedded document
fields
* **Raises:**
**AttributeError** – if `expand_schema == False` and a field does not
exist
### *class* fiftyone.core.clips.ClipsView(source_collection, clips_stage, clips_dataset, \_stages=None, \_media_type=None, \_name=None)
Bases: [`DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
A [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) of clips from a video
[`fiftyone.core.dataset.Dataset`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset).
Clips views contain an ordered collection of clips, each of which
corresponds to a range of frame numbers from the source collection.
Clips retrieved from clips views are returned as [`ClipView`](#fiftyone.core.clips.ClipView) objects.
* **Parameters:**
* **source_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) from which this
view was created
* **clips_stage** – the [`fiftyone.core.stages.ToClips`](fiftyone.core.stages.md#fiftyone.core.stages.ToClips) stage that
defines how the clips were created
* **clips_dataset** – the [`fiftyone.core.dataset.Dataset`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset) that serves
the clips in this view
**Attributes:**
| [`name`](#fiftyone.core.clips.ClipsView.name) | The name of the view if it is a saved view; otherwise None. |
|-------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
| [`is_saved`](#fiftyone.core.clips.ClipsView.is_saved) | Whether the view is a saved view or not. |
| [`media_type`](#fiftyone.core.clips.ClipsView.media_type) | The media type of the view. |
| [`app_config`](#fiftyone.core.clips.ClipsView.app_config) | Dataset-specific settings that customize how this collection is visualized in the [FiftyOne App](../user_guide/app.md#fiftyone-app). |
| [`camera_intrinsics`](#fiftyone.core.clips.ClipsView.camera_intrinsics) | The camera intrinsics of the underlying dataset. |
| [`classes`](#fiftyone.core.clips.ClipsView.classes) | The classes of the underlying dataset. |
| [`dataset_name`](#fiftyone.core.clips.ClipsView.dataset_name) | The name of the underlying dataset. |
| [`default_classes`](#fiftyone.core.clips.ClipsView.default_classes) | The default classes of the underlying dataset. |
| [`default_group_slice`](#fiftyone.core.clips.ClipsView.default_group_slice) | The default group slice of the view, or None if the view is not grouped. |
| [`default_mask_targets`](#fiftyone.core.clips.ClipsView.default_mask_targets) | The default mask targets of the underlying dataset. |
| [`default_skeleton`](#fiftyone.core.clips.ClipsView.default_skeleton) | The default keypoint skeleton of the underlying dataset. |
| [`description`](#fiftyone.core.clips.ClipsView.description) | A description of the underlying dataset. |
| [`group_field`](#fiftyone.core.clips.ClipsView.group_field) | The group field of the view, or None if the view is not grouped. |
| [`group_media_types`](#fiftyone.core.clips.ClipsView.group_media_types) | A dict mapping group slices to media types, or None if the view is not grouped. |
| [`group_slice`](#fiftyone.core.clips.ClipsView.group_slice) | The current group slice of the view, or None if the view is not grouped. |
| [`group_slices`](#fiftyone.core.clips.ClipsView.group_slices) | The list of group slices of the view, or None if the view is not grouped. |
| [`has_annotation_runs`](#fiftyone.core.clips.ClipsView.has_annotation_runs) | Whether this collection has any annotation runs. |
| [`has_brain_runs`](#fiftyone.core.clips.ClipsView.has_brain_runs) | Whether this collection has any brain runs. |
| [`has_evaluations`](#fiftyone.core.clips.ClipsView.has_evaluations) | Whether this collection has any evaluation results. |
| [`has_runs`](#fiftyone.core.clips.ClipsView.has_runs) | Whether this collection has any runs. |
| [`info`](#fiftyone.core.clips.ClipsView.info) | The info dict of the underlying dataset. |
| [`mask_targets`](#fiftyone.core.clips.ClipsView.mask_targets) | The mask targets of the underlying dataset. |
| [`skeletons`](#fiftyone.core.clips.ClipsView.skeletons) | The keypoint skeletons of the underlying dataset. |
| [`static_transforms`](#fiftyone.core.clips.ClipsView.static_transforms) | The static transforms of the underlying dataset. |
| [`tags`](#fiftyone.core.clips.ClipsView.tags) | The list of tags of the underlying dataset. |
**Methods:**
| [`set_values`](#fiftyone.core.clips.ClipsView.set_values)(field_name, \*args, \*\*kwargs) | Sets the field or embedded field on each sample or frame in the collection to the given values. |
|------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`set_label_values`](#fiftyone.core.clips.ClipsView.set_label_values)(field_name, \*args, \*\*kwargs) | Sets the fields of the specified labels in the collection to the given values. |
| [`save`](#fiftyone.core.clips.ClipsView.save)([fields]) | Saves the clips in this view to the underlying dataset. |
| [`keep`](#fiftyone.core.clips.ClipsView.keep)() | Deletes all clips that are **not** in this view from the underlying dataset. |
| [`keep_fields`](#fiftyone.core.clips.ClipsView.keep_fields)() | Deletes any frame fields that have been excluded in this view from the frames of the underlying dataset. |
| [`reload`](#fiftyone.core.clips.ClipsView.reload)() | Reloads the view. |
| [`add_stage`](#fiftyone.core.clips.ClipsView.add_stage)(stage) | Applies the given [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage) to the collection. |
| [`aggregate`](#fiftyone.core.clips.ClipsView.aggregate)(aggregations[, \_mongo]) | Aggregates one or more [`fiftyone.core.aggregations.Aggregation`](fiftyone.core.aggregations.md#fiftyone.core.aggregations.Aggregation) instances. |
| [`annotate`](#fiftyone.core.clips.ClipsView.annotate)(anno_key[, label_schema, ...]) | Exports the samples and optional label field(s) in this collection to the given annotation backend. |
| [`apply_model`](#fiftyone.core.clips.ClipsView.apply_model)(model[, label_field, ...]) | Applies the model to the samples in the collection. |
| [`bounds`](#fiftyone.core.clips.ClipsView.bounds)(field_or_expr[, expr, safe]) | Computes the bounds of a numeric field of the collection. |
| [`clear`](#fiftyone.core.clips.ClipsView.clear)() | Deletes all samples in the view from the underlying dataset. |
| [`clear_frame_field`](#fiftyone.core.clips.ClipsView.clear_frame_field)(field_name) | Clears the values of the frame-level field from all samples in the view. |
| [`clear_frame_fields`](#fiftyone.core.clips.ClipsView.clear_frame_fields)(field_names) | Clears the values of the frame-level fields from all samples in the view. |
| [`clear_frames`](#fiftyone.core.clips.ClipsView.clear_frames)() | Deletes all frame labels from the samples in the view from the underlying dataset. |
| [`clear_sample_field`](#fiftyone.core.clips.ClipsView.clear_sample_field)(field_name) | Clears the values of the field from all samples in the view. |
| [`clear_sample_fields`](#fiftyone.core.clips.ClipsView.clear_sample_fields)(field_names) | Clears the values of the fields from all samples in the view. |
| [`clone`](#fiftyone.core.clips.ClipsView.clone)([name, persistent, include_indexes]) | Creates a new dataset containing a copy of the contents of the view. |
| [`clone_frame_field`](#fiftyone.core.clips.ClipsView.clone_frame_field)(field_name, new_field_name) | Clones the frame-level field of the view into a new field. |
| [`clone_frame_fields`](#fiftyone.core.clips.ClipsView.clone_frame_fields)(field_mapping) | Clones the frame-level fields of the view into new frame-level fields of the dataset. |
| [`clone_sample_field`](#fiftyone.core.clips.ClipsView.clone_sample_field)(field_name, new_field_name) | Clones the given sample field of the view into a new field of the dataset. |
| [`clone_sample_fields`](#fiftyone.core.clips.ClipsView.clone_sample_fields)(field_mapping) | Clones the given sample fields of the view into new fields of the dataset. |
| [`compute_embeddings`](#fiftyone.core.clips.ClipsView.compute_embeddings)(model[, ...]) | Computes embeddings for the samples in the collection using the given model. |
| [`compute_metadata`](#fiftyone.core.clips.ClipsView.compute_metadata)([overwrite, num_workers, ...]) | Populates the `metadata` field of all samples in the collection. |
| [`compute_patch_embeddings`](#fiftyone.core.clips.ClipsView.compute_patch_embeddings)(model, patches_field) | Computes embeddings for the image patches defined by `patches_field` of the samples in the collection using the given model. |
| [`concat`](#fiftyone.core.clips.ClipsView.concat)(samples) | Concatenates the contents of the given `SampleCollection` to this collection. |
| [`count`](#fiftyone.core.clips.ClipsView.count)([field_or_expr, expr, safe]) | Counts the number of field values in the collection. |
| [`count_label_tags`](#fiftyone.core.clips.ClipsView.count_label_tags)([label_fields]) | Counts the occurrences of all label tags in the specified label field(s) of this collection. |
| [`count_sample_tags`](#fiftyone.core.clips.ClipsView.count_sample_tags)() | Counts the occurrences of sample tags in this collection. |
| [`count_values`](#fiftyone.core.clips.ClipsView.count_values)(field_or_expr[, expr, safe]) | Counts the occurrences of field values in the collection. |
| [`create_index`](#fiftyone.core.clips.ClipsView.create_index)(field_or_spec[, unique, force, ...]) | Creates an index on the given field or with the given specification, if necessary. |
| [`delete_annotation_run`](#fiftyone.core.clips.ClipsView.delete_annotation_run)(anno_key) | Deletes the annotation run with the given key from this collection. |
| [`delete_annotation_runs`](#fiftyone.core.clips.ClipsView.delete_annotation_runs)() | Deletes all annotation runs from this collection. |
| [`delete_brain_run`](#fiftyone.core.clips.ClipsView.delete_brain_run)(brain_key) | Deletes the brain method run with the given key from this collection. |
| [`delete_brain_runs`](#fiftyone.core.clips.ClipsView.delete_brain_runs)() | Deletes all brain method runs from this collection. |
| [`delete_evaluation`](#fiftyone.core.clips.ClipsView.delete_evaluation)(eval_key) | Deletes the evaluation results associated with the given evaluation key from this collection. |
| [`delete_evaluations`](#fiftyone.core.clips.ClipsView.delete_evaluations)() | Deletes all evaluation results from this collection. |
| [`delete_run`](#fiftyone.core.clips.ClipsView.delete_run)(run_key) | Deletes the run with the given key from this collection. |
| [`delete_runs`](#fiftyone.core.clips.ClipsView.delete_runs)() | Deletes all runs from this collection. |
| [`distinct`](#fiftyone.core.clips.ClipsView.distinct)(field_or_expr[, expr, safe]) | Computes the distinct values of a field in the collection. |
| [`draw_labels`](#fiftyone.core.clips.ClipsView.draw_labels)(output_dir[, rel_dir, ...]) | Renders annotated versions of the media in the collection with the specified label data overlaid to the given directory. |
| [`drop_index`](#fiftyone.core.clips.ClipsView.drop_index)(field_or_name) | Drops the index for the given field or name, if necessary. |
| [`ensure_frames`](#fiftyone.core.clips.ClipsView.ensure_frames)() | Ensures that the video view contains frame instances for every frame of each sample's source video. |
| [`evaluate_classifications`](#fiftyone.core.clips.ClipsView.evaluate_classifications)(pred_field[, ...]) | Evaluates the classification predictions in this collection with respect to the specified ground truth labels. |
| [`evaluate_detections`](#fiftyone.core.clips.ClipsView.evaluate_detections)(pred_field[, gt_field, ...]) | Evaluates the specified predicted detections in this collection with respect to the specified ground truth detections. |
| [`evaluate_regressions`](#fiftyone.core.clips.ClipsView.evaluate_regressions)(pred_field[, gt_field, ...]) | Evaluates the regression predictions in this collection with respect to the specified ground truth values. |
| [`evaluate_segmentations`](#fiftyone.core.clips.ClipsView.evaluate_segmentations)(pred_field[, ...]) | Evaluates the specified semantic segmentation masks in this collection with respect to the specified ground truth masks. |
| [`exclude`](#fiftyone.core.clips.ClipsView.exclude)(sample_ids) | Excludes the samples with the given IDs from the collection. |
| [`exclude_by`](#fiftyone.core.clips.ClipsView.exclude_by)(field, values) | Excludes the samples with the given field values from the collection. |
| [`exclude_fields`](#fiftyone.core.clips.ClipsView.exclude_fields)([field_names, meta_filter, ...]) | Excludes the fields with the given names from the samples in the collection. |
| [`exclude_frames`](#fiftyone.core.clips.ClipsView.exclude_frames)(frame_ids[, omit_empty]) | Excludes the frames with the given IDs from the video collection. |
| [`exclude_group_slices`](#fiftyone.core.clips.ClipsView.exclude_group_slices)([slices, media_type]) | Excludes the specified group slice(s) from the grouped collection. |
| [`exclude_groups`](#fiftyone.core.clips.ClipsView.exclude_groups)(group_ids) | Excludes the groups with the given IDs from the grouped collection. |
| [`exclude_labels`](#fiftyone.core.clips.ClipsView.exclude_labels)([labels, ids, instance_ids, ...]) | Excludes the specified labels from the collection. |
| [`exists`](#fiftyone.core.clips.ClipsView.exists)(field[, bool]) | Returns a view containing the samples in the collection that have (or do not have) a non-`None` value for the given field or embedded field. |
| [`export`](#fiftyone.core.clips.ClipsView.export)([export_dir, dataset_type, ...]) | Exports the samples in the collection to disk. |
| [`filter_field`](#fiftyone.core.clips.ClipsView.filter_field)(field, filter[, only_matches]) | Filters the values of a field or embedded field of each sample in the collection. |
| [`filter_keypoints`](#fiftyone.core.clips.ClipsView.filter_keypoints)(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. |
| [`filter_labels`](#fiftyone.core.clips.ClipsView.filter_labels)(field, filter[, only_matches, ...]) | Filters the [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) field of each sample in the collection. |
| [`first`](#fiftyone.core.clips.ClipsView.first)() | Returns the first sample in the collection. |
| [`flatten`](#fiftyone.core.clips.ClipsView.flatten)([stages]) | Returns a flattened view that contains all samples in the dynamic grouped collection. |
| [`generate_label_schemas`](#fiftyone.core.clips.ClipsView.generate_label_schemas)([fields, scan_samples]) | Generates label schemas for the [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection). |
| [`geo_near`](#fiftyone.core.clips.ClipsView.geo_near)(point[, location_field, ...]) | Sorts the samples in the collection by their proximity to a specified geolocation. |
| [`geo_within`](#fiftyone.core.clips.ClipsView.geo_within)(boundary[, location_field, ...]) | Filters the samples in this collection to only include samples whose geolocation is within a specified boundary. |
| [`get_annotation_info`](#fiftyone.core.clips.ClipsView.get_annotation_info)(anno_key) | Returns information about the annotation run with the given key on this collection. |
| [`get_brain_info`](#fiftyone.core.clips.ClipsView.get_brain_info)(brain_key) | Returns information about the brain method run with the given key on this collection. |
| [`get_classes`](#fiftyone.core.clips.ClipsView.get_classes)(field) | Gets the classes list for the given field, or None if no classes are available. |
| [`get_dynamic_field_schema`](#fiftyone.core.clips.ClipsView.get_dynamic_field_schema)([fields, recursive]) | Returns a schema dictionary describing the dynamic fields of the samples in the collection. |
| [`get_dynamic_frame_field_schema`](#fiftyone.core.clips.ClipsView.get_dynamic_frame_field_schema)([fields, ...]) | Returns a schema dictionary describing the dynamic fields of the frames in the collection. |
| [`get_dynamic_group`](#fiftyone.core.clips.ClipsView.get_dynamic_group)(group_value) | Returns a view containing the samples from a dynamic grouped view with the given group value. |
| [`get_evaluation_info`](#fiftyone.core.clips.ClipsView.get_evaluation_info)(eval_key) | Returns information about the evaluation with the given key on this collection. |
| [`get_field`](#fiftyone.core.clips.ClipsView.get_field)(path[, ftype, embedded_doc_type, ...]) | Returns the field instance of the provided path, or `None` if one does not exist. |
| [`get_field_schema`](#fiftyone.core.clips.ClipsView.get_field_schema)([ftype, embedded_doc_type, ...]) | Returns a schema dictionary describing the fields of the samples in the view. |
| [`get_frame_field_schema`](#fiftyone.core.clips.ClipsView.get_frame_field_schema)([ftype, ...]) | Returns a schema dictionary describing the fields of the frames of the samples in the view. |
| [`get_group`](#fiftyone.core.clips.ClipsView.get_group)(group_id[, group_slices]) | Returns a dict containing the samples for the given group ID. |
| [`get_index_information`](#fiftyone.core.clips.ClipsView.get_index_information)([include_stats, ...]) | Returns a dictionary of information about the indexes on this collection. |
| [`get_mask_targets`](#fiftyone.core.clips.ClipsView.get_mask_targets)(field) | Gets the mask targets for the given field, or None if no mask targets are available. |
| [`get_run_info`](#fiftyone.core.clips.ClipsView.get_run_info)(run_key) | Returns information about the run with the given key on this collection. |
| [`get_skeleton`](#fiftyone.core.clips.ClipsView.get_skeleton)(field) | Gets the keypoint skeleton for the given field, or None if no skeleton is available. |
| [`group_by`](#fiftyone.core.clips.ClipsView.group_by)(field_or_expr[, order_by, reverse, ...]) | Creates a view that groups the samples in the collection by a specified field or expression. |
| [`has_annotation_run`](#fiftyone.core.clips.ClipsView.has_annotation_run)(anno_key) | Whether this collection has an annotation run with the given key. |
| [`has_brain_run`](#fiftyone.core.clips.ClipsView.has_brain_run)(brain_key) | Whether this collection has a brain method run with the given key. |
| [`has_classes`](#fiftyone.core.clips.ClipsView.has_classes)(field) | Determines whether this collection has a classes list for the given field. |
| [`has_evaluation`](#fiftyone.core.clips.ClipsView.has_evaluation)(eval_key) | Whether this collection has an evaluation with the given key. |
| [`has_field`](#fiftyone.core.clips.ClipsView.has_field)(path) | Determines whether the collection has a field with the given name. |
| [`has_frame_field`](#fiftyone.core.clips.ClipsView.has_frame_field)(path) | Determines whether the collection has a frame-level field with the given name. |
| [`has_mask_targets`](#fiftyone.core.clips.ClipsView.has_mask_targets)(field) | Determines whether this collection has mask targets for the given field. |
| [`has_run`](#fiftyone.core.clips.ClipsView.has_run)(run_key) | Whether this collection has a run with the given key. |
| [`has_sample_field`](#fiftyone.core.clips.ClipsView.has_sample_field)(path) | Determines whether the collection has a sample field with the given name. |
| [`has_skeleton`](#fiftyone.core.clips.ClipsView.has_skeleton)(field) | Determines whether this collection has a keypoint skeleton for the given field. |
| [`head`](#fiftyone.core.clips.ClipsView.head)([num_samples]) | Returns a list of the first few samples in the collection. |
| [`histogram_values`](#fiftyone.core.clips.ClipsView.histogram_values)(field_or_expr[, expr, ...]) | Computes a histogram of the field values in the collection. |
| [`init_run`](#fiftyone.core.clips.ClipsView.init_run)(\*\*kwargs) | Initializes a config instance for a new run. |
| [`init_run_results`](#fiftyone.core.clips.ClipsView.init_run_results)(run_key, \*\*kwargs) | Initializes a results instance for the run with the given key. |
| [`iter_dynamic_groups`](#fiftyone.core.clips.ClipsView.iter_dynamic_groups)([progress]) | Returns an iterator over the dynamic groups in the view. |
| [`iter_groups`](#fiftyone.core.clips.ClipsView.iter_groups)([group_slices, progress, ...]) | Returns an iterator over the groups in the view. |
| [`iter_samples`](#fiftyone.core.clips.ClipsView.iter_samples)([progress, autosave, ...]) | Returns an iterator over the samples in the view. |
| [`keep_frames`](#fiftyone.core.clips.ClipsView.keep_frames)() | For each sample in the view, deletes all frames labels that are **not** in the view from the underlying dataset. |
| [`last`](#fiftyone.core.clips.ClipsView.last)() | Returns the last sample in the collection. |
| [`limit`](#fiftyone.core.clips.ClipsView.limit)(limit) | Returns a view with at most the given number of samples. |
| [`limit_labels`](#fiftyone.core.clips.ClipsView.limit_labels)(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 the collection. |
| [`list_aggregations`](#fiftyone.core.clips.ClipsView.list_aggregations)() | Returns a list of all available methods on this collection that apply [`fiftyone.core.aggregations.Aggregation`](fiftyone.core.aggregations.md#fiftyone.core.aggregations.Aggregation) operations to this collection. |
| [`list_annotation_runs`](#fiftyone.core.clips.ClipsView.list_annotation_runs)([type, method]) | Returns a list of annotation keys on this collection. |
| [`list_brain_runs`](#fiftyone.core.clips.ClipsView.list_brain_runs)([type, method]) | Returns a list of brain keys on this collection. |
| [`list_evaluations`](#fiftyone.core.clips.ClipsView.list_evaluations)([type, method]) | Returns a list of evaluation keys on this collection. |
| [`list_indexes`](#fiftyone.core.clips.ClipsView.list_indexes)() | Returns the list of index names on this collection. |
| [`list_runs`](#fiftyone.core.clips.ClipsView.list_runs)(\*\*kwargs) | Returns a list of run keys on this collection. |
| [`list_schema`](#fiftyone.core.clips.ClipsView.list_schema)(field_or_expr[, expr]) | Extracts the value type(s) in a specified list field across all samples in the collection. |
| [`list_view_stages`](#fiftyone.core.clips.ClipsView.list_view_stages)() | Returns a list of all available methods on this collection that apply [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage) operations to this collection. |
| [`load_annotation_results`](#fiftyone.core.clips.ClipsView.load_annotation_results)(anno_key[, cache]) | Loads the results for the annotation run with the given key on this collection. |
| [`load_annotation_view`](#fiftyone.core.clips.ClipsView.load_annotation_view)(anno_key[, select_fields]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) on which the specified annotation run was performed on this collection. |
| [`load_annotations`](#fiftyone.core.clips.ClipsView.load_annotations)(anno_key[, dest_field, ...]) | Downloads the labels from the given annotation run from the annotation backend and merges them into this collection. |
| [`load_brain_results`](#fiftyone.core.clips.ClipsView.load_brain_results)(brain_key[, cache, load_view]) | Loads the results for the brain method run with the given key on this collection. |
| [`load_brain_view`](#fiftyone.core.clips.ClipsView.load_brain_view)(brain_key[, select_fields]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) on which the specified brain method run was performed on this collection. |
| [`load_evaluation_results`](#fiftyone.core.clips.ClipsView.load_evaluation_results)(eval_key[, cache]) | Loads the results for the evaluation with the given key on this collection. |
| [`load_evaluation_view`](#fiftyone.core.clips.ClipsView.load_evaluation_view)(eval_key[, select_fields]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) on which the specified evaluation was performed on this collection. |
| [`load_run_results`](#fiftyone.core.clips.ClipsView.load_run_results)(run_key[, cache, load_view]) | Loads the results for the run with the given key on this collection. |
| [`load_run_view`](#fiftyone.core.clips.ClipsView.load_run_view)(run_key[, select_fields]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) on which the specified run was performed on this collection. |
| [`make_unique_field_name`](#fiftyone.core.clips.ClipsView.make_unique_field_name)([root]) | Makes a unique field name with the given root name for the collection. |
| [`map_labels`](#fiftyone.core.clips.ClipsView.map_labels)(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 the collection. |
| [`map_samples`](#fiftyone.core.clips.ClipsView.map_samples)(map_fcn[, save, skip_failures, ...]) | Applies the given function to each sample in the collection and returns the results as a generator. |
| [`map_values`](#fiftyone.core.clips.ClipsView.map_values)(field, map) | Maps the values in the given field to new values for each sample in the collection. |
| [`match`](#fiftyone.core.clips.ClipsView.match)(filter) | Filters the samples in the collection by the given filter. |
| [`match_frames`](#fiftyone.core.clips.ClipsView.match_frames)(filter[, omit_empty]) | Filters the frames in the video collection by the given filter. |
| [`match_labels`](#fiftyone.core.clips.ClipsView.match_labels)([labels, ids, instance_ids, ...]) | Selects the samples from the collection that contain (or do not contain) at least one label that matches the specified criteria. |
| [`match_tags`](#fiftyone.core.clips.ClipsView.match_tags)(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). |
| [`max`](#fiftyone.core.clips.ClipsView.max)(field_or_expr[, expr, safe]) | Computes the maximum of a numeric field of the collection. |
| [`mean`](#fiftyone.core.clips.ClipsView.mean)(field_or_expr[, expr, safe]) | Computes the arithmetic mean of the field values of the collection. |
| [`merge_labels`](#fiftyone.core.clips.ClipsView.merge_labels)(in_field, out_field) | Merges the labels from the given input field into the given output field of the collection. |
| [`min`](#fiftyone.core.clips.ClipsView.min)(field_or_expr[, expr, safe]) | Computes the minimum of a numeric field of the collection. |
| [`mongo`](#fiftyone.core.clips.ClipsView.mongo)(pipeline[, \_needs_frames, \_group_slices]) | Adds a view stage defined by a raw MongoDB aggregation pipeline. |
| [`one`](#fiftyone.core.clips.ClipsView.one)(expr[, exact]) | Returns a single sample in this collection matching the expression. |
| [`quantiles`](#fiftyone.core.clips.ClipsView.quantiles)(field_or_expr, quantiles[, expr, safe]) | Computes the quantile(s) of the field values of a collection. |
| [`register_run`](#fiftyone.core.clips.ClipsView.register_run)(run_key, config[, results, ...]) | Registers a run under the given key on this collection. |
| [`rename_annotation_run`](#fiftyone.core.clips.ClipsView.rename_annotation_run)(anno_key, new_anno_key) | Replaces the key for the given annotation run with a new key. |
| [`rename_brain_run`](#fiftyone.core.clips.ClipsView.rename_brain_run)(brain_key, new_brain_key) | Replaces the key for the given brain run with a new key. |
| [`rename_evaluation`](#fiftyone.core.clips.ClipsView.rename_evaluation)(eval_key, new_eval_key) | Replaces the key for the given evaluation with a new key. |
| [`rename_run`](#fiftyone.core.clips.ClipsView.rename_run)(run_key, new_run_key) | Replaces the key for the given run with a new key. |
| [`save_context`](#fiftyone.core.clips.ClipsView.save_context)([batch_size, batching_strategy]) | Returns a context that can be used to save samples from this collection according to a configurable batching strategy. |
| [`save_run_results`](#fiftyone.core.clips.ClipsView.save_run_results)(run_key, results[, ...]) | Saves run results for the run with the given key. |
| [`schema`](#fiftyone.core.clips.ClipsView.schema)(field_or_expr[, expr, dynamic_only, ...]) | Extracts the names and types of the attributes of a specified embedded document field across all samples in the collection. |
| [`select`](#fiftyone.core.clips.ClipsView.select)(sample_ids[, ordered]) | Selects the samples with the given IDs from the collection. |
| [`select_by`](#fiftyone.core.clips.ClipsView.select_by)(field, values[, ordered]) | Selects the samples with the given field values from the collection. |
| [`select_fields`](#fiftyone.core.clips.ClipsView.select_fields)([field_names, meta_filter, ...]) | Selects only the fields with the given names from the samples in the collection. |
| [`select_frames`](#fiftyone.core.clips.ClipsView.select_frames)(frame_ids[, omit_empty]) | Selects the frames with the given IDs from the video collection. |
| [`select_group_slices`](#fiftyone.core.clips.ClipsView.select_group_slices)([slices, media_type, ...]) | Selects the specified group slice(s) from the grouped collection. |
| [`select_groups`](#fiftyone.core.clips.ClipsView.select_groups)(group_ids[, ordered]) | Selects the groups with the given IDs from the grouped collection. |
| [`select_labels`](#fiftyone.core.clips.ClipsView.select_labels)([labels, ids, instance_ids, ...]) | Selects only the specified labels from the collection. |
| [`set_field`](#fiftyone.core.clips.ClipsView.set_field)(field, expr[, \_allow_missing]) | Sets a field or embedded field on each sample in a collection by evaluating the given expression. |
| [`shuffle`](#fiftyone.core.clips.ClipsView.shuffle)([seed]) | Randomly shuffles the samples in the collection. |
| [`skip`](#fiftyone.core.clips.ClipsView.skip)(skip) | Omits the given number of samples from the head of the collection. |
| [`sort_by`](#fiftyone.core.clips.ClipsView.sort_by)(field_or_expr[, reverse, create_index]) | Sorts the samples in the collection by the given field(s) or expression(s). |
| [`sort_by_similarity`](#fiftyone.core.clips.ClipsView.sort_by_similarity)(query[, k, reverse, ...]) | Sorts the collection by similarity to a specified query. |
| [`split_labels`](#fiftyone.core.clips.ClipsView.split_labels)(in_field, out_field[, filter]) | Splits the labels from the given input field into the given output field of the collection. |
| [`stats`](#fiftyone.core.clips.ClipsView.stats)([include_media, include_indexes, ...]) | Returns stats about the collection on disk. |
| [`std`](#fiftyone.core.clips.ClipsView.std)(field_or_expr[, expr, safe, sample]) | Computes the standard deviation of the field values of the collection. |
| [`sum`](#fiftyone.core.clips.ClipsView.sum)(field_or_expr[, expr, safe]) | Computes the sum of the field values of the collection. |
| [`summary`](#fiftyone.core.clips.ClipsView.summary)() | Returns a string summary of the view. |
| [`sync_last_modified_at`](#fiftyone.core.clips.ClipsView.sync_last_modified_at)([include_frames]) | Syncs the `last_modified_at` property(s) of the dataset. |
| [`tag_labels`](#fiftyone.core.clips.ClipsView.tag_labels)(tags[, label_fields]) | Adds the tag(s) to all labels in the specified label field(s) of this collection, if necessary. |
| [`tag_samples`](#fiftyone.core.clips.ClipsView.tag_samples)(tags) | Adds the tag(s) to all samples in this collection, if necessary. |
| [`tail`](#fiftyone.core.clips.ClipsView.tail)([num_samples]) | Returns a list of the last few samples in the collection. |
| [`take`](#fiftyone.core.clips.ClipsView.take)(size[, seed]) | Randomly samples the given number of samples from the collection. |
| [`to_clips`](#fiftyone.core.clips.ClipsView.to_clips)(field_or_expr, \*\*kwargs) | Creates a view that contains one sample per clip defined by the given field or expression in the video collection. |
| [`to_dict`](#fiftyone.core.clips.ClipsView.to_dict)([rel_dir, include_private, ...]) | Returns a JSON dictionary representation of the view. |
| [`to_evaluation_patches`](#fiftyone.core.clips.ClipsView.to_evaluation_patches)(eval_key, \*\*kwargs) | 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. |
| [`to_frames`](#fiftyone.core.clips.ClipsView.to_frames)(\*\*kwargs) | Creates a view that contains one sample per frame in the video collection. |
| [`to_json`](#fiftyone.core.clips.ClipsView.to_json)([rel_dir, include_private, ...]) | Returns a JSON string representation of the collection. |
| [`to_patches`](#fiftyone.core.clips.ClipsView.to_patches)(field, \*\*kwargs) | Creates a view that contains one sample per object patch in the specified field of the collection. |
| [`to_torch`](#fiftyone.core.clips.ClipsView.to_torch)(get_item, \*[, index_field, ...]) | Constructs a [`torch.utils.data.Dataset`](https://docs.pytorch.org/docs/stable/data.html#torch.utils.data.Dataset) that loads data from this collection via the provided [`fiftyone.utils.torch.GetItem`](fiftyone.utils.torch.md#fiftyone.utils.torch.GetItem) instance. |
| [`to_trajectories`](#fiftyone.core.clips.ClipsView.to_trajectories)(field, \*\*kwargs) | 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. |
| [`untag_labels`](#fiftyone.core.clips.ClipsView.untag_labels)(tags[, label_fields]) | Removes the tag from all labels in the specified label field(s) of this collection, if necessary. |
| [`untag_samples`](#fiftyone.core.clips.ClipsView.untag_samples)(tags) | Removes the tag(s) from all samples in this collection, if necessary. |
| [`update_run_config`](#fiftyone.core.clips.ClipsView.update_run_config)(run_key, config) | Updates the run config for the run with the given key. |
| [`update_samples`](#fiftyone.core.clips.ClipsView.update_samples)(update_fcn[, skip_failures, ...]) | Applies the given function to each sample in the collection and saves the resulting sample edits. |
| [`validate_field_type`](#fiftyone.core.clips.ClipsView.validate_field_type)(path[, ftype, ...]) | Validates that the collection has a field of the given type. |
| [`validate_fields_exist`](#fiftyone.core.clips.ClipsView.validate_fields_exist)(fields[, include_private]) | Validates that the collection has field(s) with the given name(s). |
| [`values`](#fiftyone.core.clips.ClipsView.values)(field_or_expr[, expr, missing_value, ...]) | Extracts the values of a field from all samples in the collection. |
| [`view`](#fiftyone.core.clips.ClipsView.view)() | Returns a copy of this view. |
| [`write_json`](#fiftyone.core.clips.ClipsView.write_json)(json_path[, rel_dir, ...]) | Writes the collection to disk in JSON format. |
#### *property* name
The name of the view if it is a saved view; otherwise None.
#### *property* is_saved
Whether the view is a saved view or not.
#### *property* media_type
The media type of the view.
#### set_values(field_name, \*args, \*\*kwargs)
Sets the field or embedded field on each sample or frame in the
collection to the given values.
You can use this method in two ways:
- **Dict syntax (recommended):** provide `values` as a dict whose
keys specify the `key_field` values of the samples whose
`field_name` you want to set to the corresponding values
- **List syntax:** provide `values` as a list, one for each sample
in the collection on which you are invoking this method
#### NOTE
The most performant strategy for setting large numbers of field
values is to use the dict syntax with `key_field="id"` when
setting sample fields and `key_field="frames.id"` when setting
frame fields. All other syntaxes internally convert to these IDs
before ultimately performing the updates.
When setting a sample field `embedded.field.name` via the list
`values` syntax, this function is an efficient implementation of the
following loop:
```default
for sample, value in zip(sample_collection, values):
sample.embedded.field.name = value
sample.save()
```
When setting an embedded field that contains an array, say
`embedded.array.field.name`, via the list `values` syntax, this
function is an efficient implementation of the following loop:
```default
for sample, array_values in zip(sample_collection, values):
for doc, value in zip(sample.embedded.array, array_values):
doc.field.name = value
sample.save()
```
When setting a frame field `frames.embedded.field.name` via the list
`values` syntax, this function is an efficient implementation of the
following loop:
```default
for sample, frame_values in zip(sample_collection, values):
for frame, value in zip(sample.frames.values(), frame_values):
frame.embedded.field.name = value
sample.save()
```
When setting an embedded frame field that contains an array, say
`frames.embedded.array.field.name`, via the list `values` syntax,
this function is an efficient implementation of the following loop:
```default
for sample, frame_values in zip(sample_collection, values):
for frame, array_values in zip(sample.frames.values(), frame_values):
for doc, value in zip(frame.embedded.array, array_values):
doc.field.name = value
sample.save()
```
When setting a sample field `embedded.field.name` via the dict
`values` syntax, this function is an efficient implementation of the
following loop:
```default
for key, value in values.items():
sample = sample_collection.one(F(key_field) == key)
sample.embedded.field.name = value
sample.save()
```
When setting frame fields using the dict `values` syntax with a
frame-level `key_field`, this function is an efficient implementation
of the following loop:
```default
frames = sample_collection.to_frames(...)
for key, value in values.items():
frame = frames.one(F(key_field) == key)
frame.embedded.field.name = value
frame.save()
```
When setting frame fields using the dict `values` syntax with a
sample-level `key_field`, each value in `values` may either be a
list corresponding to the frames of the sample matching the given key,
or each value may itself be a dict mapping frame numbers to values. In
the latter case, this function is an efficient implementation of the
following loop:
```default
for key, frame_values in values.items():
sample = sample_collection.one(F(key_field) == key)
for frame_number, value in frame_values.items():
frame = sample[frame_number]
frame.embedded.field.name = value
sample.save()
```
You can also update list fields using the dict `values` syntaxes, in
which case this method is an efficient implementation of the natural
nested list modifications of the above sample/frame loops.
The dual function of [`set_values()`](#fiftyone.core.clips.ClipsView.set_values) is [`values()`](#fiftyone.core.clips.ClipsView.values), which can be
used to efficiently extract the values of a field or embedded field of
all samples in a collection as lists of values.
#### NOTE
If you are setting attributes of a nested list of labels, such as
attributes of the objects in a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field, then consider using
[`set_label_values()`](#fiftyone.core.clips.ClipsView.set_label_values) instead for greater efficiency.
#### NOTE
If the values you are setting can be described by a
[`fiftyone.core.expressions.ViewExpression`](fiftyone.core.expressions.md#fiftyone.core.expressions.ViewExpression) applied to the
existing dataset contents, then consider using [`set_field()`](#fiftyone.core.clips.ClipsView.set_field) +
[`save()`](fiftyone.core.view.md#fiftyone.core.view.DatasetView.save) for an even
more efficient alternative to explicitly iterating over the dataset
or calling [`values()`](#fiftyone.core.clips.ClipsView.values) + [`set_values()`](#fiftyone.core.clips.ClipsView.set_values) to perform the
update in-memory.
Examples:
```default
import random
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
#
# Create a new sample field
#
# list syntax
values = [random.random() for _ in range(len(dataset))]
dataset.set_values("random", values)
print(dataset.bounds("random"))
#
# Edit a frame field
#
# dict syntax
sample_ids = dataset.values("id")
values = {id: random.random() for id in sample_ids}
dataset.set_values("random", values, key_field="id")
print(dataset.bounds("random"))
#
# Add a tag to all low confidence labels
#
view = dataset.filter_labels("predictions", F("confidence") < 0.06)
# list syntax on a filtered view
tags = view.values("predictions.detections.tags")
for sample_tags in tags:
for detection_tags in sample_tags:
detection_tags.append("low_confidence")
view.set_values("predictions.detections.tags", tags)
print(view.count("predictions.detections")) # 447
print(dataset.count_label_tags()) # 447
#
# Create a new frame field
#
dataset = foz.load_zoo_dataset("quickstart-video")
# list syntax
values = []
for sample in dataset:
values.append([random.random() for _ in sample.frames])
dataset.set_values("frames.random", values)
print(dataset.bounds("frames.random"))
#
# Edit a frame field
#
# dict syntax
frame_ids = dataset.values("frames.id", unwind=True)
values = {id: random.random() for id in frame_ids}
dataset.set_values("frames.random", values, key_field="frames.id")
print(dataset.bounds("frames.random"))
```
* **Parameters:**
* **field_name** – a field or `embedded.field.name`
* **values** –
the field values to set, provided in either of the
following formats:
- **list syntax**: an iterable of values, one for each sample
in the collection. If `field_name` contains array fields,
the corresponding elements of `values` must be arrays of
the same lengths. When setting frame fields, each element
can either be an iterable of values (one for each existing
frame of the sample) or a dict mapping frame numbers to
values
- **dict syntax**: a dict whose keys specify the `key_field`
values of the samples for which to set `field_name` to
the corresponding values. When setting frame fields, you
can either provide a sample-level `key_field`, in which
case each corresponding value in `values` must be a list
or dict of per-frame field values to set as described in
the previous bullet, or you can provide a frame-level
`key_field`, in which case each key-value pair in
`values` represents a per-frame update
* **key_field** (*None*) – a key field to use when choosing which samples to
update when `values` is a dict
* **skip_none** (*False*) – whether to treat None data in `values` as
missing data that should not be set
* **expand_schema** (*True*) – whether to dynamically add new sample/frame
fields encountered to the dataset schema. If False, an error is
raised if the root `field_name` does not exist
* **dynamic** (*False*) – whether to declare dynamic attributes of embedded
document fields that are encountered
* **validate** (*True*) – whether to validate that the values are compliant
with the dataset schema before adding them
* **progress** (*False*) – whether to render a progress bar (True/False),
use the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
#### set_label_values(field_name, \*args, \*\*kwargs)
Sets the fields of the specified labels in the collection to the
given values.
You can use this method in two ways:
- **List syntax (recommended):** provide a list of dicts of the form
`{"sample_id": sample_id, "label_id": label_id, "value": value}`
specifying the sample IDs and label IDs of each label you want to
edit
- **Dict syntax:** provide a dict mapping label IDs to values
#### NOTE
This method is most efficient when you use the list syntax, which
includes the sample/frame ID of each label that you are modifying.
#### NOTE
This method is appropriate when you have the IDs of the labels you
wish to modify. See [`set_values()`](#fiftyone.core.clips.ClipsView.set_values) and [`set_field()`](#fiftyone.core.clips.ClipsView.set_field) if
your updates are not keyed by label ID.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
#
# Populate a new boolean attribute on all high confidence labels
#
view = dataset.filter_labels("predictions", F("confidence") > 0.99)
# Option 1 (recommended): provide label IDs and sample IDs
values = []
sample_ids, label_ids = view.values(["id", "predictions.detections.id"])
for sid, lids in zip(sample_ids, label_ids):
for lid in lids:
values.append({"sample_id": sid, "label_id": lid, "value": True})
dataset.set_label_values("predictions.detections.high_conf", values)
print(dataset.count("predictions.detections"))
print(len(values))
print(dataset.count_values("predictions.detections.high_conf"))
# Option 2: provide only label IDs
label_ids = view.values("predictions.detections.id", unwind=True)
values = {_id: True for _id in label_ids}
dataset.set_label_values("predictions.detections.high_conf", values)
print(dataset.count("predictions.detections"))
print(len(label_ids))
print(dataset.count_values("predictions.detections.high_conf"))
```
* **Parameters:**
* **field_name** – a field or `embedded.field.name`
* **values** –
the label values to set, in one of the following formats:
- a list of dicts of the form
`{"sample_id": sample_id, "label_id": label_id, "value": value}`
when setting sample-level labels
- a list of dicts of the form
`{"frame_id": frame_id, "label_id": label_id, "value": value}`
when setting frame-level labels
- a dict mapping label IDs to values
* **skip_none** (*False*) – whether to treat None data in `values` as
missing data that should not be set
* **dynamic** (*False*) – whether to declare dynamic attributes of embedded
document fields that are encountered
* **validate** (*True*) – whether to validate that the values are compliant
with the dataset schema before adding them
* **progress** (*False*) – whether to render a progress bar (True/False),
use the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
#### save(fields=None)
Saves the clips in this view to the underlying dataset.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### WARNING
This will permanently delete any omitted or filtered contents from
the frames of the underlying dataset.
* **Parameters:**
**fields** (*None*) – an optional field or list of fields to save. If
specified, only these fields are overwritten
#### keep()
Deletes all clips that are **not** in this view from the underlying
dataset.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### keep_fields()
Deletes any frame fields that have been excluded in this view from
the frames of the underlying dataset.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### reload()
Reloads the view.
Note that [`ClipView`](#fiftyone.core.clips.ClipView) instances are not singletons, so any
in-memory clips extracted from this view will not be updated by calling
this method.
#### add_stage(stage)
Applies the given [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage) to the
collection.
* **Parameters:**
**stage** – a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage)
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### aggregate(aggregations, \_mongo=False)
Aggregates one or more
[`fiftyone.core.aggregations.Aggregation`](fiftyone.core.aggregations.md#fiftyone.core.aggregations.Aggregation) instances.
Note that it is best practice to group aggregations into a single call
to [`aggregate()`](#fiftyone.core.clips.ClipsView.aggregate), as this will be more efficient than performing
multiple aggregations in series.
* **Parameters:**
**aggregations** – an [`fiftyone.core.aggregations.Aggregation`](fiftyone.core.aggregations.md#fiftyone.core.aggregations.Aggregation) or
iterable of [`fiftyone.core.aggregations.Aggregation`](fiftyone.core.aggregations.md#fiftyone.core.aggregations.Aggregation)
instances
* **Returns:**
Aggregation result(s) corresponding to the input aggregation(s).
Returns a single result for a single aggregation, a list of results
for multiple aggregations, or a generator for lazy aggregations
#### annotate(anno_key, label_schema=None, label_field=None, label_type=None, classes=None, attributes=True, mask_targets=None, allow_additions=True, allow_deletions=True, allow_label_edits=True, allow_index_edits=True, allow_spatial_edits=True, media_field='filepath', backend=None, launch_editor=False, \*\*kwargs)
Exports the samples and optional label field(s) in this collection
to the given annotation backend.
The `backend` parameter controls which annotation backend to use.
Depending on the backend you use, you may want/need to provide extra
keyword arguments to this function for the constructor of the backend’s
[`fiftyone.utils.annotations.AnnotationBackendConfig`](fiftyone.utils.annotations.md#fiftyone.utils.annotations.AnnotationBackendConfig) class.
The natively provided backends and their associated config classes are:
- `"cvat"`: [`fiftyone.utils.cvat.CVATBackendConfig`](fiftyone.utils.cvat.md#fiftyone.utils.cvat.CVATBackendConfig)
- `"labelstudio"`: [`fiftyone.utils.labelstudio.LabelStudioBackendConfig`](fiftyone.utils.labelstudio.md#fiftyone.utils.labelstudio.LabelStudioBackendConfig)
- `"labelbox"`: [`fiftyone.utils.labelbox.LabelboxBackendConfig`](fiftyone.utils.labelbox.md#fiftyone.utils.labelbox.LabelboxBackendConfig)
See [this page](../integrations/annotation.md#requesting-annotations) for more information
about using this method, including how to define label schemas and how
to configure login credentials for your annotation provider.
* **Parameters:**
* **anno_key** – a string key to use to refer to this annotation run
* **label_schema** (*None*) – a dictionary defining the label schema to use.
If this argument is provided, it takes precedence over the
other schema-related arguments
* **label_field** (*None*) – a string indicating a new or existing label
field to annotate
* **label_type** (*None*) –
a string indicating the type of labels to
annotate. The possible values are:
- `"classification"`: a single classification stored in
[`fiftyone.core.labels.Classification`](fiftyone.core.labels.md#fiftyone.core.labels.Classification) fields
- `"classifications"`: multilabel classifications stored in
[`fiftyone.core.labels.Classifications`](fiftyone.core.labels.md#fiftyone.core.labels.Classifications) fields
- `"detections"`: object detections stored in
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) fields
- `"instances"`: instance segmentations stored in
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) fields with their
[`mask`](fiftyone.core.labels.md#fiftyone.core.labels.Detection.mask)
attributes populated
- `"polylines"`: polylines stored in
[`fiftyone.core.labels.Polylines`](fiftyone.core.labels.md#fiftyone.core.labels.Polylines) fields with their
[`filled`](fiftyone.core.labels.md#fiftyone.core.labels.Polyline.filled)
attributes set to `False`
- `"polygons"`: polygons stored in
[`fiftyone.core.labels.Polylines`](fiftyone.core.labels.md#fiftyone.core.labels.Polylines) fields with their
[`filled`](fiftyone.core.labels.md#fiftyone.core.labels.Polyline.filled)
attributes set to `True`
- `"keypoints"`: keypoints stored in
[`fiftyone.core.labels.Keypoints`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoints) fields
- `"segmentation"`: semantic segmentations stored in
[`fiftyone.core.labels.Segmentation`](fiftyone.core.labels.md#fiftyone.core.labels.Segmentation) fields
- `"scalar"`: scalar labels stored in
[`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField),
[`fiftyone.core.fields.FloatField`](fiftyone.core.fields.md#fiftyone.core.fields.FloatField),
[`fiftyone.core.fields.StringField`](fiftyone.core.fields.md#fiftyone.core.fields.StringField), or
[`fiftyone.core.fields.BooleanField`](fiftyone.core.fields.md#fiftyone.core.fields.BooleanField) fields
All new label fields must have their type specified via this
argument or in `label_schema`. Note that annotation backends
may not support all label types
* **classes** (*None*) – a list of strings indicating the class options for
`label_field` or all fields in `label_schema` without
classes specified. All new label fields must have a class list
provided via one of the supported methods. For existing label
fields, if classes are not provided by this argument nor
`label_schema`, they are retrieved from [`get_classes()`](#fiftyone.core.clips.ClipsView.get_classes)
if possible, or else the observed labels on your dataset are
used
* **attributes** (*True*) –
specifies the label attributes of each label
field to include (other than their `label`, which is always
included) in the annotation export. Can be any of the
following:
- `True`: export all label attributes
- `False`: don’t export any custom label attributes
- a list of label attributes to export
- a dict mapping attribute names to dicts specifying the
`type`, `values`, and `default` for each attribute
If a `label_schema` is also provided, this parameter
determines which attributes are included for all fields that do
not explicitly define their per-field attributes (in addition
to any per-class attributes)
* **mask_targets** (*None*) – a dict mapping pixel values (2D masks) or RGB
hex strings (3D masks) to semantic label strings. Only
applicable when annotating semantic segmentations. All new
label fields must have mask targets provided via one of the
supported methods. For existing label fields, if mask targets
are not provided by this argument nor `label_schema`, any
applicable mask targets stored on your dataset will be used, if
available
* **allow_additions** (*True*) – whether to allow new labels to be added.
Only applicable when editing existing label fields
* **allow_deletions** (*True*) – whether to allow labels to be deleted. Only
applicable when editing existing label fields
* **allow_label_edits** (*True*) – whether to allow the `label` attribute
of existing labels to be modified. Only applicable when editing
existing fields with `label` attributes
* **allow_index_edits** (*True*) – whether to allow the `index` attribute
of existing video tracks to be modified. Only applicable when
editing existing frame fields with `index` attributes
* **allow_spatial_edits** (*True*) – whether to allow edits to the spatial
properties (bounding boxes, vertices, keypoints, masks, etc) of
labels. Only applicable when editing existing spatial label
fields
* **media_field** ( *"filepath"*) – the field containing the paths to the
media files to upload
* **backend** (*None*) – the annotation backend to use. The supported values
are `fiftyone.annotation_config.backends.keys()` and the
default is `fiftyone.annotation_config.default_backend`
* **launch_editor** (*False*) – whether to launch the annotation backend’s
editor after uploading the samples
* **\*\*kwargs** – keyword arguments for the
[`fiftyone.utils.annotations.AnnotationBackendConfig`](fiftyone.utils.annotations.md#fiftyone.utils.annotations.AnnotationBackendConfig)
* **Returns:**
an `fiftyone.utils.annotations.AnnnotationResults`
#### *property* app_config
Dataset-specific settings that customize how this collection is
visualized in the [FiftyOne App](../user_guide/app.md#fiftyone-app).
#### apply_model(model, label_field='predictions', confidence_thresh=None, classes=None, store_logits=False, batch_size=None, num_workers=None, skip_failures=True, output_dir=None, rel_dir=None, progress=None, \*\*kwargs)
Applies the model to the samples in the collection.
This method supports all of the following cases:
- Applying an image model to an image collection
- Applying an image model to the frames of a video collection
- Applying a video model to a video collection
* **Parameters:**
* **model** – a [`fiftyone.core.models.Model`](fiftyone.core.models.md#fiftyone.core.models.Model), Hugging Face
transformers model, Ultralytics model, SuperGradients model, or
Lightning Flash model
* **label_field** ( *"predictions"*) – the name of the field in which to
store the model predictions. When performing inference on video
frames, the “frames.” prefix is optional
* **confidence_thresh** (*None*) – an optional confidence threshold to apply
to any applicable labels generated by the model
* **classes** (*None*) – an optional iterable of classes to which to
restrict any applicable labels generated by the model
* **store_logits** (*False*) – whether to store logits for the model
predictions. This is only supported when the provided `model`
has logits, `model.has_logits == True`
* **batch_size** (*None*) – an optional batch size to use, if the model
supports batching
* **num_workers** (*None*) – the number of workers for the
[`torch.utils.data.DataLoader`](https://docs.pytorch.org/docs/stable/data.html#torch.utils.data.DataLoader) to use. Only
applicable for Torch-based models
* **skip_failures** (*True*) – whether to gracefully continue without
raising an error if predictions cannot be generated for a
sample. Only applicable to [`fiftyone.core.models.Model`](fiftyone.core.models.md#fiftyone.core.models.Model)
instances
* **output_dir** (*None*) – an optional output directory in which to write
segmentation images. Only applicable if the model generates
segmentations. If none is provided, the segmentations are
stored in the database
* **rel_dir** (*None*) – an optional relative directory to strip from each
input filepath to generate a unique identifier that is joined
with `output_dir` to generate an output path for each
segmentation image. This argument allows for populating nested
subdirectories in `output_dir` that match the shape of the
input paths. The path is converted to an absolute path (if
necessary) via [`fiftyone.core.storage.normalize_path()`](fiftyone.core.storage.md#fiftyone.core.storage.normalize_path)
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **\*\*kwargs** – optional model-specific keyword arguments passed through
to the underlying inference implementation
#### bounds(field_or_expr, expr=None, safe=False)
Computes the bounds of a numeric field of the collection.
`None`-valued fields are ignored.
This aggregation is typically applied to *numeric* or *date* field
types (or lists of such types):
- [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField)
- [`fiftyone.core.fields.FloatField`](fiftyone.core.fields.md#fiftyone.core.fields.FloatField)
- [`fiftyone.core.fields.DateField`](fiftyone.core.fields.md#fiftyone.core.fields.DateField)
- [`fiftyone.core.fields.DateTimeField`](fiftyone.core.fields.md#fiftyone.core.fields.DateTimeField)
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",
numeric_field=1.0,
numeric_list_field=[1, 2, 3],
),
fo.Sample(
filepath="/path/to/image2.png",
numeric_field=4.0,
numeric_list_field=[1, 2],
),
fo.Sample(
filepath="/path/to/image3.png",
numeric_field=None,
numeric_list_field=None,
),
]
)
#
# Compute the bounds of a numeric field
#
bounds = dataset.bounds("numeric_field")
print(bounds) # (min, max)
#
# Compute the bounds of a numeric list field
#
bounds = dataset.bounds("numeric_list_field")
print(bounds) # (min, max)
#
# Compute the bounds of a transformation of a numeric field
#
bounds = dataset.bounds(2 * (F("numeric_field") + 1))
print(bounds) # (min, max)
```
* **Parameters:**
* **field_or_expr** – a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate. This can also
be a list or tuple of such arguments, in which case a tuple of
corresponding aggregation results (each receiving the same
additional keyword arguments, if any) will be returned
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **safe** (*False*) – whether to ignore nan/inf values when dealing with
floating point values
* **Returns:**
the `(min, max)` bounds
#### *property* camera_intrinsics
The camera intrinsics of the underlying dataset.
See [`fiftyone.core.dataset.Dataset.camera_intrinsics()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.camera_intrinsics) for more
information.
#### *property* classes
The classes of the underlying dataset.
See [`fiftyone.core.dataset.Dataset.classes()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.classes) for more information.
#### clear()
Deletes all samples in the view from the underlying dataset.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### clear_frame_field(field_name)
Clears the values of the frame-level field from all samples in the
view.
The field will remain in the dataset’s frame schema, and all frames in
the view will have the value `None` for the field.
You can use dot notation (`embedded.field.name`) to clear embedded
frame fields.
Only applicable to views that contain videos.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### WARNING
If the field name you specify is an embedded field, be aware that
this operation will save the entire top-level field after clearing
the field, which may result in data modification/loss if this view
modifies the field in any other ways.
* **Parameters:**
**field_name** – the field name or `embedded.field.name`
#### clear_frame_fields(field_names)
Clears the values of the frame-level fields from all samples in the
view.
The fields will remain in the dataset’s frame schema, and all frames in
the view will have the value `None` for the fields.
You can use dot notation (`embedded.field.name`) to clear embedded
frame fields.
Only applicable to views that contain videos.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### WARNING
If any of the field names you specify are embedded fields, be aware
that this operation will save the entire top-level field after
clearing the fields, which may result in data modification/loss if
this view modifies these fields in any other ways.
* **Parameters:**
**field_names** – the field name or iterable of field names
#### clear_frames()
Deletes all frame labels from the samples in the view from the
underlying dataset.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### clear_sample_field(field_name)
Clears the values of the field from all samples in the view.
The field will remain in the dataset’s schema, and all samples in the
view will have the value `None` for the field.
You can use dot notation (`embedded.field.name`) to clear embedded
fields.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### WARNING
If the field name you specify is an embedded field, be aware that
this operation will save the entire top-level field after clearing
the field, which may result in data modification/loss if this view
modifies the field in any other ways.
* **Parameters:**
**field_name** – the field name or `embedded.field.name`
#### clear_sample_fields(field_names)
Clears the values of the fields from all samples in the view.
The fields will remain in the dataset’s schema, and all samples in the
view will have the value `None` for the fields.
You can use dot notation (`embedded.field.name`) to clear embedded
fields.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### WARNING
If any of the field names you specify are embedded fields, be aware
that this operation will save the entire top-level field after
clearing the fields, which may result in data modification/loss if
this view modifies these fields in any other ways.
* **Parameters:**
**field_names** – the field name or iterable of field names
#### clone(name=None, persistent=False, include_indexes=False)
Creates a new dataset containing a copy of the contents of the view.
Dataset clones contain deep copies of all samples and dataset-level
information in the source collection. The source *media files*,
however, are not copied.
* **Parameters:**
* **name** (*None*) – a name for the cloned dataset. By default,
`get_default_dataset_name()` is used
* **persistent** (*False*) – whether the cloned dataset should be persistent
* **include_indexes** (*False*) – whether to recreate any custom indexes on
the new dataset (True) or a list of specific indexes or index
prefixes to recreate. By default, no custom indexes are
recreated
* **Returns:**
the new [`fiftyone.core.dataset.Dataset`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset)
#### clone_frame_field(field_name, new_field_name)
Clones the frame-level field of the view into a new field.
You can use dot notation (`embedded.field.name`) to clone embedded
frame fields.
Only applicable to views that contain videos.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### WARNING
If `new_field_name` is an embedded field, be aware that this
operation will save the entire top-level field of
`new_field_name` after performing the clone, which may result in
data modification/loss if this view modifies this field in any
other ways.
* **Parameters:**
* **field_name** – the field name or `embedded.field.name`
* **new_field_name** – the new field name or `embedded.field.name`
#### clone_frame_fields(field_mapping)
Clones the frame-level fields of the view into new frame-level
fields of the dataset.
You can use dot notation (`embedded.field.name`) to clone embedded
frame fields.
Only applicable to views that contain videos.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### WARNING
If any of the new field names to specify are embedded fields, be
aware that this operation will save the entire top-level new
fields after performing the clone, which may result in data
modification/loss if this view modifies these fields in any other
ways.
* **Parameters:**
**field_mapping** – a dict mapping field names to new field names into
which to clone each field
#### clone_sample_field(field_name, new_field_name)
Clones the given sample field of the view into a new field of the
dataset.
You can use dot notation (`embedded.field.name`) to clone embedded
fields.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### WARNING
If `new_field_name` is an embedded field, be aware that this
operation will save the entire top-level field of
`new_field_name` after performing the clone, which may result in
data modification/loss if this view modifies this field in any
other ways.
* **Parameters:**
* **field_name** – the field name or `embedded.field.name`
* **new_field_name** – the new field name or `embedded.field.name`
#### clone_sample_fields(field_mapping)
Clones the given sample fields of the view into new fields of the
dataset.
You can use dot notation (`embedded.field.name`) to clone embedded
fields.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### WARNING
If any of the new field names to specify are embedded fields, be
aware that this operation will save the entire top-level new
fields after performing the clone, which may result in data
modification/loss if this view modifies these fields in any other
ways.
* **Parameters:**
**field_mapping** – a dict mapping field names to new field names into
which to clone each field
#### compute_embeddings(model, embeddings_field=None, batch_size=None, num_workers=None, skip_failures=True, progress=None, \*\*kwargs)
Computes embeddings for the samples in the collection using the
given model.
This method supports all the following cases:
- Using an image model to compute embeddings for an image collection
- Using an image model to compute frame embeddings for a video
collection
- Using a video model to compute embeddings for a video collection
The `model` must expose embeddings, i.e.,
[`fiftyone.core.models.Model.has_embeddings()`](fiftyone.core.models.md#fiftyone.core.models.Model.has_embeddings) must return `True`.
If an `embeddings_field` is provided, the embeddings are saved to the
samples; otherwise, the embeddings are returned in-memory.
* **Parameters:**
* **model** – a [`fiftyone.core.models.Model`](fiftyone.core.models.md#fiftyone.core.models.Model), Hugging Face
Transformers model, Ultralytics model, SuperGradients model, or
Lightning Flash model
* **embeddings_field** (*None*) – the name of a field in which to store the
embeddings. When computing video frame embeddings, the
“frames.” prefix is optional
* **batch_size** (*None*) – an optional batch size to use, if the model
supports batching
* **num_workers** (*None*) – the number of workers for the
[`torch.utils.data.DataLoader`](https://docs.pytorch.org/docs/stable/data.html#torch.utils.data.DataLoader) to use. Only
applicable for Torch-based models
* **skip_failures** (*True*) – whether to gracefully continue without
raising an error if embeddings cannot be generated for a
sample. Only applicable to [`fiftyone.core.models.Model`](fiftyone.core.models.md#fiftyone.core.models.Model)
instances
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **\*\*kwargs** – optional model-specific keyword arguments passed through
to the underlying inference implementation
* **Returns:**
- `None`, if an `embeddings_field` is provided
- a `num_samples x num_dim` array of embeddings, when computing
embeddings for image/video collections with image/video models,
respectively, and no `embeddings_field` is provided. If
`skip_failures` is `True` and any errors are detected, a
list of length `num_samples` is returned instead containing
all successfully computed embedding vectors along with `None`
entries for samples for which embeddings could not be computed
- a dictionary mapping sample IDs to `num_frames x num_dim`
arrays of embeddings, when computing frame embeddings for video
collections using an image model. If `skip_failures` is
`True` and any errors are detected, the values of this
dictionary will contain arrays of embeddings for all frames
1, 2, … until the error occurred, or `None` if no
embeddings were computed at all
* **Return type:**
one of the following
#### compute_metadata(overwrite=False, num_workers=None, skip_failures=True, warn_failures=True, progress=None)
Populates the `metadata` field of all samples in the collection.
Any samples with existing metadata are skipped, unless
`overwrite == True`.
* **Parameters:**
* **overwrite** (*False*) – whether to overwrite existing metadata
* **num_workers** (*None*) – a suggested number of threads to use
* **skip_failures** (*True*) – whether to gracefully continue without
raising an error if metadata cannot be computed for a sample
* **warn_failures** (*True*) – whether to log a warning if metadata cannot
be computed for a sample
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
#### compute_patch_embeddings(model, patches_field, embeddings_field=None, force_square=False, alpha=None, handle_missing='skip', batch_size=None, num_workers=None, skip_failures=True, progress=None)
Computes embeddings for the image patches defined by
`patches_field` of the samples in the collection using the given
model.
This method supports all the following cases:
- Using an image model to compute patch embeddings for an image
collection
- Using an image model to compute frame patch embeddings for a video
collection
The `model` must expose embeddings, i.e.,
[`fiftyone.core.models.Model.has_embeddings()`](fiftyone.core.models.md#fiftyone.core.models.Model.has_embeddings) must return `True`.
If an `embeddings_field` is provided, the embeddings are saved to the
samples; otherwise, the embeddings are returned in-memory.
* **Parameters:**
* **model** – a [`fiftyone.core.models.Model`](fiftyone.core.models.md#fiftyone.core.models.Model), Hugging Face
Transformers model, Ultralytics model, SuperGradients model,
or Lightning Flash model
* **patches_field** – the name of the field defining the image patches in
each sample to embed. Must be of type
[`fiftyone.core.labels.Detection`](fiftyone.core.labels.md#fiftyone.core.labels.Detection),
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections),
[`fiftyone.core.labels.Polyline`](fiftyone.core.labels.md#fiftyone.core.labels.Polyline), or
[`fiftyone.core.labels.Polylines`](fiftyone.core.labels.md#fiftyone.core.labels.Polylines). When computing video
frame embeddings, the “frames.” prefix is optional
* **embeddings_field** (*None*) – the name of a label attribute in which to
store the embeddings
* **force_square** (*False*) – whether to minimally manipulate the patch
bounding boxes into squares prior to extraction
* **alpha** (*None*) – an optional expansion/contraction to apply to the
patches before extracting them, in `[-1, inf)`. If provided,
the length and width of the box are expanded (or contracted,
when `alpha < 0`) by `(100 * alpha)%`. For example, set
`alpha = 0.1` to expand the boxes by 10%, and set
`alpha = -0.1` to contract the boxes by 10%
* **handle_missing** ( *"skip"*) –
how to handle images with no patches.
Supported values are:
- ”skip”: skip the image and assign its embedding as `None`
- ”image”: use the whole image as a single patch
- ”error”: raise an error
* **batch_size** (*None*) – an optional batch size to use, if the model
supports batching
* **num_workers** (*None*) – the number of workers for the
[`torch.utils.data.DataLoader`](https://docs.pytorch.org/docs/stable/data.html#torch.utils.data.DataLoader) to use. Only
applicable for Torch-based models
* **skip_failures** (*True*) – whether to gracefully continue without
raising an error if embeddings cannot be generated for a sample
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **Returns:**
- `None`, if an `embeddings_field` is provided
- a dict mapping sample IDs to `num_patches x num_dim` arrays
of patch embeddings, when computing patch embeddings for image
collections and no `embeddings_field` is provided. If
`skip_failures` is `True` and any errors are detected, this
dictionary will contain `None` values for any samples for
which embeddings could not be computed
- a dict of dicts mapping sample IDs to frame numbers to
`num_patches x num_dim` arrays of patch embeddings, when
computing patch embeddings for the frames of video collections
and no `embeddings_field` is provided. If `skip_failures`
is `True` and any errors are detected, this nested dict will
contain missing or `None` values to indicate uncomputable
embeddings
* **Return type:**
one of the following
#### concat(samples)
Concatenates the contents of the given `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)
view = view1.concat(view2)
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:]
patches = patches1.concat(patches2)
print(patches1)
print(patches2)
print(patches)
```
* **Parameters:**
**samples** – a `SampleCollection` whose contents to append to
this collection
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### count(field_or_expr=None, expr=None, safe=False)
Counts the number of field values in the collection.
`None`-valued fields are ignored.
If no field is provided, the samples themselves are counted.
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"),
fo.Detection(label="dog"),
]
),
),
fo.Sample(
filepath="/path/to/image2.png",
predictions=fo.Detections(
detections=[
fo.Detection(label="cat"),
fo.Detection(label="rabbit"),
fo.Detection(label="squirrel"),
]
),
),
fo.Sample(
filepath="/path/to/image3.png",
predictions=None,
),
]
)
#
# Count the number of samples in the dataset
#
count = dataset.count()
print(count) # the count
#
# Count the number of samples with `predictions`
#
count = dataset.count("predictions")
print(count) # the count
#
# Count the number of objects in the `predictions` field
#
count = dataset.count("predictions.detections")
print(count) # the count
#
# Count the number of objects in samples with > 2 predictions
#
count = dataset.count(
(F("predictions.detections").length() > 2).if_else(
F("predictions.detections"), None
)
)
print(count) # the count
```
* **Parameters:**
* **field_or_expr** (*None*) –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate. If neither
`field_or_expr` or `expr` is provided, the samples
themselves are counted. This can also be a list or tuple of
such arguments, in which case a tuple of corresponding
aggregation results (each receiving the same additional keyword
arguments, if any) will be returned
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **safe** (*False*) – whether to ignore nan/inf values when dealing with
floating point values
* **Returns:**
the count
#### count_label_tags(label_fields=None)
Counts the occurrences of all label tags in the specified label
field(s) of this collection.
* **Parameters:**
**label_fields** (*None*) – an optional name or iterable of names of
[`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) fields. By default, all
label fields are used
* **Returns:**
a dict mapping tags to counts
#### count_sample_tags()
Counts the occurrences of sample tags in this collection.
* **Returns:**
a dict mapping tags to counts
#### count_values(field_or_expr, expr=None, safe=False)
Counts the occurrences of field values in the collection.
This aggregation is typically applied to *countable* field types (or
lists of such types):
- [`fiftyone.core.fields.BooleanField`](fiftyone.core.fields.md#fiftyone.core.fields.BooleanField)
- [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField)
- [`fiftyone.core.fields.StringField`](fiftyone.core.fields.md#fiftyone.core.fields.StringField)
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",
tags=["sunny"],
predictions=fo.Detections(
detections=[
fo.Detection(label="cat"),
fo.Detection(label="dog"),
]
),
),
fo.Sample(
filepath="/path/to/image2.png",
tags=["cloudy"],
predictions=fo.Detections(
detections=[
fo.Detection(label="cat"),
fo.Detection(label="rabbit"),
]
),
),
fo.Sample(
filepath="/path/to/image3.png",
predictions=None,
),
]
)
#
# Compute the tag counts in the dataset
#
counts = dataset.count_values("tags")
print(counts) # dict mapping values to counts
#
# Compute the predicted label counts in the dataset
#
counts = dataset.count_values("predictions.detections.label")
print(counts) # dict mapping values to counts
#
# Compute the predicted label counts after some normalization
#
counts = dataset.count_values(
F("predictions.detections.label").map_values(
{"cat": "pet", "dog": "pet"}
).upper()
)
print(counts) # dict mapping values to counts
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate. This can also
be a list or tuple of such arguments, in which case a tuple of
corresponding aggregation results (each receiving the same
additional keyword arguments, if any) will be returned
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **safe** (*False*) – whether to treat nan/inf values as None when dealing
with floating point values
* **Returns:**
a dict mapping values to counts
#### create_index(field_or_spec, unique=False, force=False, wait=True, \*\*kwargs)
Creates an index on the given field or with the given specification,
if necessary.
Indexes enable efficient sorting, merging, and other such operations.
Frame-level fields can be indexed by prepending `"frames."` to the
field name.
#### NOTE
If a matching non-unique index exists and you request a unique
index, the existing index will be converted to a unique index.
If a matching unique index exists and you request a non-unique
index, the existing index will **only** be converted to a
non-unique index if you specify `force=True`.
#### NOTE
If an index with the same field(s) but different order(s) already
exists, the existing index will **only** be replaced with a new
index if you specify `force=True`.
* **Parameters:**
* **field_or_spec** – the field name, `embedded.field.name`, or index
specification list. See
[`pymongo.collection.Collection.create_index()`](https://pymongo.readthedocs.io/en/stable/api/pymongo/collection.html#pymongo.collection.Collection.create_index) for
supported values
* **unique** (*False*) – whether to add a uniqueness constraint to the index
* **force** (*False*) – whether to convert an existing unique index to a
non-unique index or replace an existing index with different
orderings with a new index. By default, existing indexes will
not be modified in these cases
* **wait** (*True*) – whether to wait for index creation to finish
* **\*\*kwargs** – optional keyword arguments for
[`pymongo.collection.Collection.create_index()`](https://pymongo.readthedocs.io/en/stable/api/pymongo/collection.html#pymongo.collection.Collection.create_index)
* **Returns:**
the name of the index
#### *property* dataset_name
The name of the underlying dataset.
#### *property* default_classes
The default classes of the underlying dataset.
See [`fiftyone.core.dataset.Dataset.default_classes()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.default_classes) for more
information.
#### *property* default_group_slice
The default group slice of the view, or None if the view is not
grouped.
#### *property* default_mask_targets
The default mask targets of the underlying dataset.
See [`fiftyone.core.dataset.Dataset.default_mask_targets()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.default_mask_targets) for more
information.
#### *property* default_skeleton
The default keypoint skeleton of the underlying dataset.
See [`fiftyone.core.dataset.Dataset.default_skeleton()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.default_skeleton) for more
information.
#### delete_annotation_run(anno_key)
Deletes the annotation run with the given key from this collection.
Calling this method only deletes the **record** of the annotation run
from the collection; it will not delete any annotations loaded onto
your dataset via [`load_annotations()`](#fiftyone.core.clips.ClipsView.load_annotations), nor will it delete any
associated information from the annotation backend.
Use [`load_annotation_results()`](#fiftyone.core.clips.ClipsView.load_annotation_results) to programmatically manage/delete
a run from the annotation backend.
* **Parameters:**
**anno_key** – an annotation key
#### delete_annotation_runs()
Deletes all annotation runs from this collection.
Calling this method only deletes the **records** of the annotation runs
from this collection; it will not delete any annotations loaded onto
your dataset via [`load_annotations()`](#fiftyone.core.clips.ClipsView.load_annotations), nor will it delete any
associated information from the annotation backend.
Use [`load_annotation_results()`](#fiftyone.core.clips.ClipsView.load_annotation_results) to programmatically manage/delete
runs in the annotation backend.
#### delete_brain_run(brain_key)
Deletes the brain method run with the given key from this
collection.
* **Parameters:**
**brain_key** – a brain key
#### delete_brain_runs()
Deletes all brain method runs from this collection.
#### delete_evaluation(eval_key)
Deletes the evaluation results associated with the given evaluation
key from this collection.
* **Parameters:**
**eval_key** – an evaluation key
#### delete_evaluations()
Deletes all evaluation results from this collection.
#### delete_run(run_key)
Deletes the run with the given key from this collection.
* **Parameters:**
**run_key** – a run key
#### delete_runs()
Deletes all runs from this collection.
#### *property* description
A description of the underlying dataset.
See [`fiftyone.core.dataset.Dataset.description()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.description) for more
information.
#### distinct(field_or_expr, expr=None, safe=False)
Computes the distinct values of a field in the collection.
`None`-valued fields are ignored.
This aggregation is typically applied to *countable* field types (or
lists of such types):
- [`fiftyone.core.fields.BooleanField`](fiftyone.core.fields.md#fiftyone.core.fields.BooleanField)
- [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField)
- [`fiftyone.core.fields.StringField`](fiftyone.core.fields.md#fiftyone.core.fields.StringField)
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",
tags=["sunny"],
predictions=fo.Detections(
detections=[
fo.Detection(label="cat"),
fo.Detection(label="dog"),
]
),
),
fo.Sample(
filepath="/path/to/image2.png",
tags=["sunny", "cloudy"],
predictions=fo.Detections(
detections=[
fo.Detection(label="cat"),
fo.Detection(label="rabbit"),
]
),
),
fo.Sample(
filepath="/path/to/image3.png",
predictions=None,
),
]
)
#
# Get the distinct tags in a dataset
#
values = dataset.distinct("tags")
print(values) # list of distinct values
#
# Get the distinct predicted labels in a dataset
#
values = dataset.distinct("predictions.detections.label")
print(values) # list of distinct values
#
# Get the distinct predicted labels after some normalization
#
values = dataset.distinct(
F("predictions.detections.label").map_values(
{"cat": "pet", "dog": "pet"}
).upper()
)
print(values) # list of distinct values
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate. This can also
be a list or tuple of such arguments, in which case a tuple of
corresponding aggregation results (each receiving the same
additional keyword arguments, if any) will be returned
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **safe** (*False*) – whether to ignore nan/inf values when dealing with
floating point values
* **Returns:**
a sorted list of distinct values
#### draw_labels(output_dir, rel_dir=None, label_fields=None, overwrite=False, config=None, progress=None, \*\*kwargs)
Renders annotated versions of the media in the collection with the
specified label data overlaid to the given directory.
The filenames of the sample media are maintained, unless a name
conflict would occur in `output_dir`, in which case an index of the
form `"-%d" % count` is appended to the base filename.
Images are written in format `fo.config.default_image_ext`, and
videos are written in format `fo.config.default_video_ext`.
* **Parameters:**
* **output_dir** – the directory to write the annotated media
* **rel_dir** (*None*) – an optional relative directory to strip from each
input filepath to generate a unique identifier that is joined
with `output_dir` to generate an output path for each
annotated media. This argument allows for populating nested
subdirectories in `output_dir` that match the shape of the
input paths. The path is converted to an absolute path (if
necessary) via [`fiftyone.core.storage.normalize_path()`](fiftyone.core.storage.md#fiftyone.core.storage.normalize_path)
* **label_fields** (*None*) – a label field or list of label fields to
render. By default, all [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label)
fields are drawn
* **overwrite** (*False*) – whether to delete `output_dir` if it exists
before rendering
* **config** (*None*) – an optional
[`fiftyone.utils.annotations.DrawConfig`](fiftyone.utils.annotations.md#fiftyone.utils.annotations.DrawConfig) configuring how
to draw the labels
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **\*\*kwargs** – optional keyword arguments specifying parameters of the
default [`fiftyone.utils.annotations.DrawConfig`](fiftyone.utils.annotations.md#fiftyone.utils.annotations.DrawConfig) to
override
* **Returns:**
the list of paths to the rendered media
#### drop_index(field_or_name)
Drops the index for the given field or name, if necessary.
* **Parameters:**
**field_or_name** – a field name, `embedded.field.name`, or compound
index name. Use [`list_indexes()`](#fiftyone.core.clips.ClipsView.list_indexes) to see the available
indexes
#### ensure_frames()
Ensures that the video view contains frame instances for every frame
of each sample’s source video.
Empty frames will be inserted for missing frames, and already existing
frames are left unchanged.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### evaluate_classifications(pred_field, gt_field='ground_truth', eval_key=None, classes=None, missing=None, method=None, progress=None, \*\*kwargs)
Evaluates the classification predictions in this collection with
respect to the specified ground truth labels.
By default, this method simply compares the ground truth and prediction
for each sample, but other strategies such as binary evaluation and
top-k matching can be configured via the `method` parameter.
You can customize the evaluation method by passing additional
parameters for the method’s config class as `kwargs`.
The natively provided `method` values and their associated configs
are:
- `"simple"`: [`fiftyone.utils.eval.classification.SimpleEvaluationConfig`](fiftyone.utils.eval.classification.md#fiftyone.utils.eval.classification.SimpleEvaluationConfig)
- `"top-k"`: [`fiftyone.utils.eval.classification.TopKEvaluationConfig`](fiftyone.utils.eval.classification.md#fiftyone.utils.eval.classification.TopKEvaluationConfig)
- `"binary"`: [`fiftyone.utils.eval.classification.BinaryEvaluationConfig`](fiftyone.utils.eval.classification.md#fiftyone.utils.eval.classification.BinaryEvaluationConfig)
If an `eval_key` is specified, then this method will record some
statistics on each sample:
- When evaluating sample-level fields, an `eval_key` field will be
populated on each sample recording whether that sample’s prediction
is correct.
- When evaluating frame-level fields, an `eval_key` field will be
populated on each frame recording whether that frame’s prediction
is correct. In addition, an `eval_key` field will be populated on
each sample that records the average accuracy of the frame
predictions of the sample.
* **Parameters:**
* **pred_field** – the name of the field containing the predicted
[`fiftyone.core.labels.Classification`](fiftyone.core.labels.md#fiftyone.core.labels.Classification) instances
* **gt_field** ( *"ground_truth"*) – the name of the field containing the
ground truth [`fiftyone.core.labels.Classification`](fiftyone.core.labels.md#fiftyone.core.labels.Classification)
instances
* **eval_key** (*None*) – a string key to use to refer to this evaluation
* **classes** (*None*) – the list of possible classes. If not provided,
the observed ground truth/predicted labels are used
* **missing** (*None*) – a missing label string. Any None-valued labels
are given this label for results purposes
* **method** (*None*) – a string specifying the evaluation method to use.
The supported values are
`fo.evaluation_config.classification_backends.keys()` and the
default is `fo.evaluation_config.classification_default_backend`
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **\*\*kwargs** – optional keyword arguments for the constructor of the
[`fiftyone.utils.eval.classification.ClassificationEvaluationConfig`](fiftyone.utils.eval.classification.md#fiftyone.utils.eval.classification.ClassificationEvaluationConfig)
being used
* **Returns:**
a [`fiftyone.utils.eval.classification.ClassificationResults`](fiftyone.utils.eval.classification.md#fiftyone.utils.eval.classification.ClassificationResults)
#### evaluate_detections(pred_field, gt_field='ground_truth', eval_key=None, classes=None, missing=None, method=None, iou=0.5, use_masks=False, use_boxes=False, classwise=True, dynamic=True, progress=None, \*\*kwargs)
Evaluates the specified predicted detections in this collection with
respect to the specified ground truth detections.
This method supports evaluating the following spatial data types:
- Object detections in [`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) format
- Instance segmentations in [`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections)
format with their `mask` attributes populated
- Polygons in [`fiftyone.core.labels.Polylines`](fiftyone.core.labels.md#fiftyone.core.labels.Polylines) format
- Keypoints in [`fiftyone.core.labels.Keypoints`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoints) format
- Temporal detections in
[`fiftyone.core.labels.TemporalDetections`](fiftyone.core.labels.md#fiftyone.core.labels.TemporalDetections) format
For spatial object detection evaluation, this method uses COCO-style
evaluation by default.
When evaluating keypoints, “IoUs” are computed via
[object keypoint similarity](https://cocodataset.org/#keypoints-eval).
You can pass `keypoint_sigmas` to customize the per-keypoint OKS
falloff.
For temporal segment detection, this method uses ActivityNet-style
evaluation by default.
You can use the `method` parameter to select a different method, and
you can optionally customize the method by passing additional
parameters for the method’s config class as `kwargs`.
The natively provided `method` values and their associated configs
are:
- `"coco"`: [`fiftyone.utils.eval.coco.COCOEvaluationConfig`](fiftyone.utils.eval.coco.md#fiftyone.utils.eval.coco.COCOEvaluationConfig)
- `"open-images"`: [`fiftyone.utils.eval.openimages.OpenImagesEvaluationConfig`](fiftyone.utils.eval.openimages.md#fiftyone.utils.eval.openimages.OpenImagesEvaluationConfig)
- `"activitynet"`: [`fiftyone.utils.eval.activitynet.ActivityNetEvaluationConfig`](fiftyone.utils.eval.activitynet.md#fiftyone.utils.eval.activitynet.ActivityNetEvaluationConfig)
If an `eval_key` is provided, a number of fields are populated at the
object- and sample-level recording the results of the evaluation:
- True positive (TP), false positive (FP), and false negative (FN)
counts for the each sample are saved in top-level fields of each
sample:
```default
TP: sample._tp
FP: sample._fp
FN: sample._fn
```
In addition, when evaluating frame-level objects, TP/FP/FN counts
are recorded for each frame:
```default
TP: frame._tp
FP: frame._fp
FN: frame._fn
```
- The fields listed below are populated on each individual object;
these fields tabulate the TP/FP/FN status of the object, the ID of
the matching object (if any), and the matching IoU:
```default
TP/FP/FN: object.
ID: object._id
IoU: object._iou
```
* **Parameters:**
* **pred_field** – the name of the field containing the predicted
[`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),
or [`fiftyone.core.labels.TemporalDetections`](fiftyone.core.labels.md#fiftyone.core.labels.TemporalDetections)
* **gt_field** ( *"ground_truth"*) – the name of the field containing the
ground truth [`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),
or [`fiftyone.core.labels.TemporalDetections`](fiftyone.core.labels.md#fiftyone.core.labels.TemporalDetections)
* **eval_key** (*None*) – a string key to use to refer to this evaluation
* **classes** (*None*) – the list of possible classes. If not provided,
the observed ground truth/predicted labels are used
* **missing** (*None*) – a missing label string. Any unmatched objects are
given this label for results purposes
* **method** (*None*) – a string specifying the evaluation method to use.
The supported values are
`fo.evaluation_config.detection_backends.keys()` and the
default is `fo.evaluation_config.detection_default_backend`
* **iou** (*0.50*) – the IoU threshold to use to determine matches
* **use_masks** (*False*) – whether to compute IoUs using the instances
masks in the `mask` attribute of the provided objects, which
must be [`fiftyone.core.labels.Detection`](fiftyone.core.labels.md#fiftyone.core.labels.Detection) instances
* **use_boxes** (*False*) – whether to compute IoUs using the bounding boxes
of the provided [`fiftyone.core.labels.Polyline`](fiftyone.core.labels.md#fiftyone.core.labels.Polyline)
instances rather than using their actual geometries
* **classwise** (*True*) – whether to only match objects with the same class
label (True) or allow matches between classes (False)
* **dynamic** (*True*) – whether to declare the dynamic object-level
attributes that are populated on the dataset’s schema
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **\*\*kwargs** – optional keyword arguments for the constructor of the
[`fiftyone.utils.eval.detection.DetectionEvaluationConfig`](fiftyone.utils.eval.detection.md#fiftyone.utils.eval.detection.DetectionEvaluationConfig)
being used
* **Returns:**
a [`fiftyone.utils.eval.detection.DetectionResults`](fiftyone.utils.eval.detection.md#fiftyone.utils.eval.detection.DetectionResults)
#### evaluate_regressions(pred_field, gt_field='ground_truth', eval_key=None, missing=None, method=None, progress=None, \*\*kwargs)
Evaluates the regression predictions in this collection with respect
to the specified ground truth values.
You can customize the evaluation method by passing additional
parameters for the method’s config class as `kwargs`.
The natively provided `method` values and their associated configs
are:
- `"simple"`: [`fiftyone.utils.eval.regression.SimpleEvaluationConfig`](fiftyone.utils.eval.regression.md#fiftyone.utils.eval.regression.SimpleEvaluationConfig)
If an `eval_key` is specified, then this method will record some
statistics on each sample:
- When evaluating sample-level fields, an `eval_key` field will be
populated on each sample recording the error of that sample’s
prediction.
- When evaluating frame-level fields, an `eval_key` field will be
populated on each frame recording the error of that frame’s
prediction. In addition, an `eval_key` field will be populated on
each sample that records the average error of the frame predictions
of the sample.
* **Parameters:**
* **pred_field** – the name of the field containing the predicted
[`fiftyone.core.labels.Regression`](fiftyone.core.labels.md#fiftyone.core.labels.Regression) instances
* **gt_field** ( *"ground_truth"*) – the name of the field containing the
ground truth [`fiftyone.core.labels.Regression`](fiftyone.core.labels.md#fiftyone.core.labels.Regression) instances
* **eval_key** (*None*) – a string key to use to refer to this evaluation
* **missing** (*None*) – a missing value. Any None-valued regressions are
given this value for results purposes
* **method** (*None*) – a string specifying the evaluation method to use.
The supported values are
`fo.evaluation_config.regression_backends.keys()` and the
default is `fo.evaluation_config.regression_default_backend`
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **\*\*kwargs** – optional keyword arguments for the constructor of the
[`fiftyone.utils.eval.regression.RegressionEvaluationConfig`](fiftyone.utils.eval.regression.md#fiftyone.utils.eval.regression.RegressionEvaluationConfig)
being used
* **Returns:**
a [`fiftyone.utils.eval.regression.RegressionResults`](fiftyone.utils.eval.regression.md#fiftyone.utils.eval.regression.RegressionResults)
#### evaluate_segmentations(pred_field, gt_field='ground_truth', eval_key=None, mask_targets=None, method=None, progress=None, \*\*kwargs)
Evaluates the specified semantic segmentation masks in this
collection with respect to the specified ground truth masks.
If the size of a predicted mask does not match the ground truth mask,
it is resized to match the ground truth.
By default, this method simply performs pixelwise evaluation of the
full masks, but other strategies such as boundary-only evaluation can
be configured by passing additional parameters for the method’s
config class as `kwargs`.
The natively provided `method` values and their associated configs
are:
- `"simple"`: [`fiftyone.utils.eval.segmentation.SimpleEvaluationConfig`](fiftyone.utils.eval.segmentation.md#fiftyone.utils.eval.segmentation.SimpleEvaluationConfig)
If an `eval_key` is provided, the accuracy, precision, and recall of
each sample is recorded in top-level fields of each sample:
```default
Accuracy: sample._accuracy
Precision: sample._precision
Recall: sample._recall
```
In addition, when evaluating frame-level masks, the accuracy,
precision, and recall of each frame if recorded in the following
frame-level fields:
```default
Accuracy: frame._accuracy
Precision: frame._precision
Recall: frame._recall
```
#### NOTE
The mask values `0` and `#000000` are treated as a background
class for the purposes of computing evaluation metrics like
precision and recall.
* **Parameters:**
* **pred_field** – the name of the field containing the predicted
[`fiftyone.core.labels.Segmentation`](fiftyone.core.labels.md#fiftyone.core.labels.Segmentation) instances
* **gt_field** ( *"ground_truth"*) – the name of the field containing the
ground truth [`fiftyone.core.labels.Segmentation`](fiftyone.core.labels.md#fiftyone.core.labels.Segmentation)
instances
* **eval_key** (*None*) – a string key to use to refer to this evaluation
* **mask_targets** (*None*) – a dict mapping pixel values (2D masks) or RGB
hex strings (3D masks) to semantic label strings. If not
provided, the observed values are used as labels
* **method** (*None*) – a string specifying the evaluation method to use.
The supported values are
`fo.evaluation_config.segmentation_backends.keys()` and the
default is `fo.evaluation_config.segmentation_default_backend`
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **\*\*kwargs** – optional keyword arguments for the constructor of the
[`fiftyone.utils.eval.segmentation.SegmentationEvaluationConfig`](fiftyone.utils.eval.segmentation.md#fiftyone.utils.eval.segmentation.SegmentationEvaluationConfig)
being used
* **Returns:**
a [`fiftyone.utils.eval.segmentation.SegmentationResults`](fiftyone.utils.eval.segmentation.md#fiftyone.utils.eval.segmentation.SegmentationResults)
#### exclude(sample_ids)
Excludes the samples with the given IDs from the 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
view = dataset.exclude(sample_id)
#
# Exclude the first and last samples from the dataset
#
sample_ids = [dataset.first().id, dataset.last().id]
view = dataset.exclude(sample_ids)
```
* **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)
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### exclude_by(field, values)
Excludes the samples with the given field values from the
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.clips.ClipsView.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
#
view = dataset.exclude_by("int", [1, 9, 3, 7, 5])
print(view.head(5))
#
# Create a view excluding samples whose `str` field have the given
# values
#
view = dataset.exclude_by("str", ["1", "9", "3", "7", "5"])
print(view.head(5))
```
* **Parameters:**
* **field** – a field or `embedded.field.name`
* **values** – a value or iterable of values to exclude by
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### exclude_fields(field_names=None, meta_filter=None, \_allow_missing=False)
Excludes the fields with the given names from the samples in the
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
#
view = dataset.exclude_fields("predictions")
#
# Exclude the `mood` attribute from all classifications in the
# `predictions` field
#
view = dataset.exclude_fields("predictions.mood")
```
* **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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### exclude_frames(frame_ids, omit_empty=True)
Excludes the frames with the given IDs from the 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,
]
view = dataset.exclude_frames(frame_ids)
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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### exclude_group_slices(slices=None, media_type=None)
Excludes the specified group slice(s) from the 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 samples from the "ego" group slice
#
view = dataset.exclude_group_slices("ego")
#
# Exclude the samples from the "left" or "right" group slices
#
view = dataset.exclude_group_slices(["left", "right"])
#
# Exclude all image slices
#
view = dataset.exclude_group_slices(media_type="image")
```
* **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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### exclude_groups(group_ids)
Excludes the groups with the given IDs from the 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")
other_groups = dataset.exclude_groups(group_ids)
assert len(set(group_ids) & set(other_groups.values("group.id"))) == 0
```
* **Parameters:**
**groups_ids** –
the groups to exclude. 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)
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### exclude_labels(labels=None, ids=None, instance_ids=None, tags=None, fields=None, omit_empty=True)
Excludes the specified labels from the 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...
view = dataset.exclude_labels(labels=session.selected_labels)
#
# Exclude labels with the specified IDs
#
# Grab some label IDs
ids = [
dataset.first().ground_truth.detections[0].id,
dataset.last().predictions.detections[0].id,
]
view = dataset.exclude_labels(ids=ids)
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
view = dataset.exclude_labels(tags="test")
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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### exists(field, bool=None)
Returns a view containing the samples in the 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
#
view = dataset.exists("predictions")
#
# Only include samples that do NOT have a value in their
# `predictions` field
#
view = dataset.exists("predictions", False)
#
# Only include samples that have prediction confidences
#
view = dataset.exists("predictions.confidence")
```
* **Parameters:**
* **field** – the field name or `embedded.field.name`
* **bool** (*None*) – whether to check if the field exists (None or True) or
does not exist (False)
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### export(export_dir=None, dataset_type=None, data_path=None, labels_path=None, export_media=None, rel_dir=None, dataset_exporter=None, label_field=None, frame_labels_field=None, overwrite=False, progress=None, \*\*kwargs)
Exports the samples in the collection to disk.
You can perform exports with this method via the following basic
patterns:
1. Provide `export_dir` and `dataset_type` to export the content
to a directory in the default layout for the specified format, as
documented in [this page](../user_guide/export_datasets.md#exporting-datasets)
2. Provide `dataset_type` along with `data_path`, `labels_path`,
and/or `export_media` to directly specify where to export the
source media and/or labels (if applicable) in your desired format.
This syntax provides the flexibility to, for example, perform
workflows like labels-only exports
3. Provide a `dataset_exporter` to which to feed samples to perform
a fully-customized export
In all workflows, the remaining parameters of this method can be
provided to further configure the export.
See [this page](../user_guide/export_datasets.md#exporting-datasets) for more information about
the available export formats and examples of using this method.
See [this guide](../user_guide/export_datasets.md#custom-dataset-exporter) for more details about
exporting datasets in custom formats by defining your own
[`fiftyone.utils.data.exporters.DatasetExporter`](fiftyone.utils.data.exporters.md#fiftyone.utils.data.exporters.DatasetExporter).
This method will automatically coerce the data to match the requested
export in the following cases:
- When exporting in either an unlabeled image or image classification
format, if a spatial label field is provided
([`fiftyone.core.labels.Detection`](fiftyone.core.labels.md#fiftyone.core.labels.Detection),
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections),
[`fiftyone.core.labels.Polyline`](fiftyone.core.labels.md#fiftyone.core.labels.Polyline), or
[`fiftyone.core.labels.Polylines`](fiftyone.core.labels.md#fiftyone.core.labels.Polylines)), then the
**image patches** of the provided samples will be exported
- When exporting in labeled image dataset formats that expect
list-type labels ([`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), or
[`fiftyone.core.labels.Polylines`](fiftyone.core.labels.md#fiftyone.core.labels.Polylines)), if a label field contains
labels in non-list format
(e.g., [`fiftyone.core.labels.Classification`](fiftyone.core.labels.md#fiftyone.core.labels.Classification)), the labels
will be automatically upgraded to single-label lists
- When exporting in labeled image dataset formats that expect
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) labels, if a
[`fiftyone.core.labels.Classification`](fiftyone.core.labels.md#fiftyone.core.labels.Classification) field is provided, the
labels will be automatically upgraded to detections that span the
entire images
* **Parameters:**
* **export_dir** (*None*) –
the directory to which to export the samples in
format `dataset_type`. This parameter may be omitted if you
have provided appropriate values for the `data_path` and/or
`labels_path` parameters. Alternatively, this can also be an
archive path with one of the following extensions:
```default
.zip, .tar, .tar.gz, .tgz, .tar.bz, .tbz
```
If an archive path is specified, the export is performed in a
directory of same name (minus extension) and then automatically
archived and the directory then deleted
* **dataset_type** (*None*) – the [`fiftyone.types.Dataset`](fiftyone.types.md#fiftyone.types.Dataset) type to
write. If not specified, the default type for `label_field`
is used
* **data_path** (*None*) –
an optional parameter that enables explicit
control over the location of the exported media for certain
export formats. Can be any of the following:
- a folder name like `"data"` or `"data/"` specifying a
subfolder of `export_dir` in which to export the media
- an absolute directory path in which to export the media. In
this case, the `export_dir` has no effect on the location
of the data
- a filename like `"data.json"` specifying the filename of
a JSON manifest file in `export_dir` generated when
`export_media` is `"manifest"`
- an absolute filepath specifying the location to write the
JSON manifest file when `export_media` is `"manifest"`.
In this case, `export_dir` has no effect on the location
of the data
If None, a default value of this parameter will be chosen based
on the value of the `export_media` parameter. Note that this
parameter is not applicable to certain export formats such as
binary types like TF records
* **labels_path** (*None*) –
an optional parameter that enables explicit
control over the location of the exported labels. Only
applicable when exporting in certain labeled dataset formats.
Can be any of the following:
- a type-specific folder name like `"labels"` or
`"labels/"` or a filename like `"labels.json"` or
`"labels.xml"` specifying the location in `export_dir`
in which to export the labels
- an absolute directory or filepath in which to export the
labels. In this case, the `export_dir` has no effect on
the location of the labels
For labeled datasets, the default value of this parameter will
be chosen based on the export format so that the labels will be
exported into `export_dir`
* **export_media** (*None*) –
controls how to export the raw media. The
supported values are:
- `True`: copy all media files into the output directory
- `False`: don’t export media. This option is only useful
when exporting labeled datasets whose label format stores
sufficient information to locate the associated media
- `"move"`: move all media files into the output directory
- `"symlink"`: create symlinks to the media files in the
output directory
- `"manifest"`: create a `data.json` in the output
directory that maps UUIDs used in the labels files to the
filepaths of the source media, rather than exporting the
actual media
If None, an appropriate default value of this parameter will be
chosen based on the value of the `data_path` parameter. Note
that some dataset formats may not support certain values for
this parameter (e.g., when exporting in binary formats such as
TF records, “symlink” is not an option)
* **rel_dir** (*None*) – an optional relative directory to strip from each
input filepath to generate a unique identifier for each media.
When exporting media, this identifier is joined with
`data_path` to generate an output path for each exported
media. This argument allows for populating nested
subdirectories that match the shape of the input paths. The
path is converted to an absolute path (if necessary) via
[`fiftyone.core.storage.normalize_path()`](fiftyone.core.storage.md#fiftyone.core.storage.normalize_path)
* **dataset_exporter** (*None*) – a
[`fiftyone.utils.data.exporters.DatasetExporter`](fiftyone.utils.data.exporters.md#fiftyone.utils.data.exporters.DatasetExporter) to use
to export the samples. When provided, parameters such as
`export_dir`, `dataset_type`, `data_path`, and
`labels_path` have no effect
* **label_field** (*None*) –
controls the label field(s) to export. Only
applicable to labeled datasets. Can be any of the following:
- the name of a label field to export
- a glob pattern of label field(s) to export
- a list or tuple of label field(s) to export
- a dictionary mapping label field names to keys to use when
constructing the label dictionaries to pass to the exporter
Note that multiple fields can only be specified when the
exporter used can handle dictionaries of labels. By default,
the first field of compatible type for the exporter is used.
When exporting labeled video datasets, this argument may
contain frame fields prefixed by `"frames."`
* **frame_labels_field** (*None*) –
controls the frame label field(s) to
export. The `"frames."` prefix is optional. Only applicable
to labeled video datasets. Can be any of the following:
- the name of a frame label field to export
- a glob pattern of frame label field(s) to export
- a list or tuple of frame label field(s) to export
- a dictionary mapping frame label field names to keys to use
when constructing the frame label dictionaries to pass to
the exporter
Note that multiple fields can only be specified when the
exporter used can handle dictionaries of frame labels. By
default, the first field of compatible type for the exporter is
used
* **overwrite** (*False*) – whether to delete existing directories before
performing the export (True) or to merge the export with
existing files and directories (False)
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **\*\*kwargs** – optional keyword arguments to pass to the dataset
exporter’s constructor. If you are exporting image patches,
this can also contain keyword arguments for
[`fiftyone.utils.patches.ImagePatchesExtractor`](fiftyone.utils.patches.md#fiftyone.utils.patches.ImagePatchesExtractor)
#### filter_field(field, filter, only_matches=True)
Filters the values of a field or embedded field of each sample in
the 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"
#
view = dataset.filter_field("predictions", F("label") == "cat")
#
# Only include samples whose `numeric_field` value is positive
#
view = dataset.filter_field("numeric_field", F() > 0)
```
* **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 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)
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### filter_keypoints(field, filter=None, labels=None, only_matches=True)
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 [`filter_labels()`](#fiftyone.core.clips.ClipsView.filter_labels) 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
#
view = dataset.filter_keypoints(
"predictions", filter=F("confidence") > 0.9
)
#
# Only include keypoints in the `predictions` field with less than
# four points
#
view = dataset.filter_keypoints(
"predictions", labels=["left eye", "right eye"]
)
```
* **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)
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### filter_labels(field, filter, only_matches=True, trajectories=False)
Filters the [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) field of each
sample in the 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
#
view = dataset.filter_labels("predictions", F("confidence") > 0.8)
#
# Only include classifications in the `predictions` field whose
# `label` is "cat" or "dog"
#
view = dataset.filter_labels(
"predictions", F("label").is_in(["cat", "dog"])
)
```
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
#
view = dataset.filter_labels("predictions", F("confidence") > 0.8)
#
# Only include detections in the `predictions` field whose `label`
# is "cat" or "dog"
#
view = dataset.filter_labels(
"predictions", F("label").is_in(["cat", "dog"])
)
#
# 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]
view = dataset.filter_labels("predictions", bbox_area < 0.2)
```
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
#
view = dataset.filter_labels("predictions", F("filled") == True)
#
# Only include polylines in the `predictions` field whose `label`
# is "lane"
#
view = dataset.filter_labels("predictions", F("label") == "lane")
#
# Only include polylines in the `predictions` field with at least
# 3 vertices
#
num_vertices = F("points").map(F().length()).sum()
view = dataset.filter_labels("predictions", num_vertices >= 3)
```
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"
#
view = dataset.filter_labels("predictions", F("label") == "house")
#
# Only include keypoints in the `predictions` field with less than
# four points
#
view = dataset.filter_labels("predictions", F("points").length() < 4)
```
* **Parameters:**
* **field** – the label field to filter
* **filter** –
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 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 datasets that contain videos and
frame-level label fields whose objects have their `index`
attributes populated
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### first()
Returns the first sample in the collection.
* **Returns:**
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)
#### flatten(stages=None)
Returns a flattened view that contains all samples in the 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
flat_view = grouped_view.flatten(fo.Limit(10))
print(len(flat_view)) # 100
```
* **Parameters:**
**stages** (*None*) – a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage) or list of
[`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage) instances to apply to
each group’s samples while flattening
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### generate_label_schemas(fields=None, scan_samples=True)
Generates label schemas for the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection).
A label schema is defined by a `type` and `component` with respect
to a field. Further settings depend on the `type` and `component`
combination as outlined below.
The `type` value for a field is inferred from the collection’s field
schema. See
[`fiftyone.core.collections.SampleCollection.get_field_schema()`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection.get_field_schema)
Currently supported media types for the collection are `image` and
`3d`. See
[`fiftyone.core.collections.SampleCollection.media_type`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection.media_type)
**Primitives and components**
Supported primitive types are:
> - `bool`: [`fiftyone.core.fields.BooleanField`](fiftyone.core.fields.md#fiftyone.core.fields.BooleanField)
> - `date`: [`fiftyone.core.fields.DateField`](fiftyone.core.fields.md#fiftyone.core.fields.DateField)
> - `datetime`: [`fiftyone.core.fields.DateTimeField`](fiftyone.core.fields.md#fiftyone.core.fields.DateTimeField)
> - `dict`: [`fiftyone.core.fields.DictField`](fiftyone.core.fields.md#fiftyone.core.fields.DictField)
> - `float`: [`fiftyone.core.fields.FloatField`](fiftyone.core.fields.md#fiftyone.core.fields.FloatField)
> - `id`: [`fiftyone.core.fields.ObjectIdField`](fiftyone.core.fields.md#fiftyone.core.fields.ObjectIdField) or
> [`fiftyone.core.fields.UUIDField`](fiftyone.core.fields.md#fiftyone.core.fields.UUIDField)
> - `int`: [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField) or
> [`fiftyone.core.fields.FrameNumberField`](fiftyone.core.fields.md#fiftyone.core.fields.FrameNumberField)
> - `list`: [`fiftyone.core.fields.ListField`](fiftyone.core.fields.md#fiftyone.core.fields.ListField) of
> [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField)
> - `list`: [`fiftyone.core.fields.ListField`](fiftyone.core.fields.md#fiftyone.core.fields.ListField) of
> [`fiftyone.core.fields.FloatField`](fiftyone.core.fields.md#fiftyone.core.fields.FloatField)
> - `list`: [`fiftyone.core.fields.ListField`](fiftyone.core.fields.md#fiftyone.core.fields.ListField) of
> [`fiftyone.core.fields.StringField`](fiftyone.core.fields.md#fiftyone.core.fields.StringField)
> - `str`: [`fiftyone.core.fields.StringField`](fiftyone.core.fields.md#fiftyone.core.fields.StringField)
Supported `bool` components are:
> - `checkbox`
> - `toggle` - the default
`date` and `datetime` only support the `datepicker` component.
`dict` only supports the `json` component.
Supported `float` and `int` components are:
> - `dropdown`
> - `radio`
> - `slider`: the default when `scan_samples` is `True` and
> distinct finite bounds are found that define a `range`
> - `text`: the default when `scan_samples` is `False` or
> distinct finite bounds are not found
Supported `list` and `list` components are:
> - `checkboxes`
> - `dropdown`
> - `text` - the default
Supported `list` components are:
> - `checkboxes`: the default if `<=5` values are scanned
> - `dropdown`: the default if `>5` and `<=1000` values are
> scanned
> - `text`: the default if `0` values or `>1000` values are
> scanned, or `scan_samples` is `False`
Supported `str` type components are:
> - `dropdown`: the default if `>5` and `<=1000` values are
> scanned
> - `radio`: the default if `<=5` values are scanned
> - `text`: the default if `0` values or `>1000` values are
> scanned, or `scan_samples` is `False`
`float` types support a `precision` setting when a `text`
component is configured for the number of digits to allow after the
decimal.
All types support a `read_only` flag. `id` types must be
`read_only`. If a field is `read_only` in the field schema, then
the `read_only` label schema setting must be `True`, e.g.
`created_at` and `last_modified_at` must be read only.
All components support `values` except `json`, `slider`, and
`toggle` excepting `id` restrictions.
`checkboxes` and `dropdown` require the `values` setting.
`slider` requires the `range: [min, max]` setting.
**Labels**
The `label` subfield of all label types are configured via `classes`
and support the same settings as a `str` type. See the example output
below for `detections` fields in the quickstart dataset. If the label
type has a visual representation, that field is handled by the App’s
builtin annotation UI, e.g. `bounding_box` for a `detection`.
Primitive attributes of label types are configured via the
`attributes` list.
When a label is marked as `read_only`, all its attributes inherit the
setting as well.
All [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) types are resolved by this
method except [`fiftyone.core.labels.GeoLocation`](fiftyone.core.labels.md#fiftyone.core.labels.GeoLocation),
[`fiftyone.core.labels.GeoLocations`](fiftyone.core.labels.md#fiftyone.core.labels.GeoLocations),
[`fiftyone.core.labels.TemporalDetection`](fiftyone.core.labels.md#fiftyone.core.labels.TemporalDetection), and
[`fiftyone.core.labels.TemporalDetections`](fiftyone.core.labels.md#fiftyone.core.labels.TemporalDetections) when provided
in the `fields` argument, otherwise only App supported fields are
resolved. For label types supported
by the App for annotation, see
[`fiftyone.core.annotation.utils.get_supported_app_annotation_fields()`](fiftyone.core.annotation.utils.md#fiftyone.core.annotation.utils.get_supported_app_annotation_fields).
All attributes and the label class itself support a `default` setting
that applies when creating a new label.
**Embedded documents**
One level of nesting is supported via `dot.notation` for
`fiftyone.core.fields.EmbeddedDocumentField`` fields for the
default `metadata` field and the
`fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument``
document type. All label and primitive types are supported. See
[here](../user_guide/using_datasets.md#dynamic-attributes) for more details on adding dynamic
attributes.
Example:
```default
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("quickstart")
dataset.compute_metadata()
fo.pprint(dataset.generate_label_schemas(scan_samples=False))
```
Output:
```default
{
"created_at": {
"type": "datetime",
"component": "datepicker",
"read_only": True,
},
"filepath": {"type": "str", "component": "text"},
"ground_truth": {
"attributes": [
{
"name": "attributes",
"type": "dict",
"component": "json",
},
{
"name": "confidence",
"type": "float",
"component": "text",
},
{
"name": "id",
"type": "id",
"component": "text",
"read_only": True,
},
{"name": "index", "type": "int", "component": "text"},
{
"name": "mask_path",
"type": "str",
"component": "text",
},
{
"name": "tags",
"type": "list",
"component": "text",
},
],
"component": "text",
"type": "detections",
},
"id": {"type": "id", "component": "text", "read_only": True},
"last_modified_at": {
"type": "datetime",
"component": "datepicker",
"read_only": True,
},
"metadata.height": {"type": "int", "component": "text"},
"metadata.mime_type": {"type": "str", "component": "text"},
"metadata.num_channels": {"type": "int", "component": "text"},
"metadata.size_bytes": {"type": "int", "component": "text"},
"metadata.width": {"type": "int", "component": "text"},
"predictions": {
"attributes": [
{
"name": "attributes",
"type": "dict",
"component": "json",
},
{
"name": "confidence",
"type": "float",
"component": "text",
},
{
"name": "id",
"type": "id",
"component": "text",
"read_only": True,
},
{"name": "index", "type": "int", "component": "text"},
{
"name": "mask_path",
"type": "str",
"component": "text",
},
{
"name": "tags",
"type": "list",
"component": "text",
},
],
"component": "text",
"type": "detections",
},
"tags": {"type": "list", "component": "text"},
"uniqueness": {"type": "float", "component": "text"},
}
```
* **Parameters:**
* **fields** (*None*) – a field name, `embedded.field.name` or iterable of
such values
* **scan_samples** (*True*) – whether to scan the collection to populate
component settings based on actual field values (ranges,
values, etc). If False, the label schema is generated from
*only* the statically available information in the dataset’s
field schema
* **Raises:**
**ValueError** – if the sample collection or field is not supported
* **Returns:**
a label schemas `dict`, or an individual field’s label schema
`dict` if only one field is provided
#### geo_near(point, location_field=None, min_distance=None, max_distance=None, query=None, create_index=False)
Sorts the samples in the 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
#
view = dataset.geo_near(TIMES_SQUARE, create_index=True)
#
# Sort the samples by their proximity to Times Square, and only
# include samples within 5km
#
view = dataset.geo_near(
TIMES_SQUARE,
max_distance=5000,
create_index=True,
)
#
# 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],
]
]
)
view = dataset.geo_near(
TIMES_SQUARE,
location_field="location",
query=in_manhattan,
create_index=True,
)
```
* **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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### geo_within(boundary, location_field=None, strict=True, create_index=False)
Filters the samples in this collection to only include 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
#
view = dataset.geo_within(MANHATTAN)
```
* **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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### get_annotation_info(anno_key)
Returns information about the annotation run with the given key on
this collection.
* **Parameters:**
**anno_key** – an annotation key
* **Returns:**
a [`fiftyone.core.annotation.AnnotationInfo`](fiftyone.core.annotation.md#fiftyone.core.annotation.AnnotationInfo)
#### get_brain_info(brain_key)
Returns information about the brain method run with the given key on
this collection.
* **Parameters:**
**brain_key** – a brain key
* **Returns:**
a [`fiftyone.core.brain.BrainInfo`](fiftyone.core.brain.md#fiftyone.core.brain.BrainInfo)
#### get_classes(field)
Gets the classes list for the given field, or None if no classes
are available.
Classes are first retrieved from [`classes()`](#fiftyone.core.clips.ClipsView.classes) if they exist,
otherwise from [`default_classes()`](#fiftyone.core.clips.ClipsView.default_classes).
* **Parameters:**
**field** – a field name
* **Returns:**
a list of classes, or None
#### get_dynamic_field_schema(fields=None, recursive=True)
Returns a schema dictionary describing the dynamic fields of the
samples in the collection.
Dynamic fields are embedded document fields with at least one non-None
value that have not been declared on the dataset’s schema.
* **Parameters:**
* **fields** (*None*) – an optional field or iterable of fields for which to
return dynamic fields. By default, all fields are considered
* **recursive** (*True*) – whether to recursively inspect nested lists and
embedded documents
* **Returns:**
a dict mapping field paths to [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
instances or lists of them
#### get_dynamic_frame_field_schema(fields=None, recursive=True)
Returns a schema dictionary describing the dynamic fields of the
frames in the collection.
Dynamic fields are embedded document fields with at least one non-None
value that have not been declared on the dataset’s schema.
* **Parameters:**
* **fields** (*None*) – an optional field or iterable of fields for which to
return dynamic fields. By default, all fields are considered
* **recursive** (*True*) – whether to recursively inspect nested lists and
embedded documents
* **Returns:**
a dict mapping field paths to [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
instances or lists of them, or `None` if the collection does not
contain videos
#### get_dynamic_group(group_value)
Returns a view containing the samples from a dynamic grouped view
with the given group value.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("cifar10", split="test")
view = dataset.take(1000).group_by("ground_truth.label")
group = view.get_dynamic_group("cat")
print(len(group)) # 104
```
* **Parameters:**
**group_value** – the group value
* **Returns:**
a `DatasetView`
#### get_evaluation_info(eval_key)
Returns information about the evaluation with the given key on this
collection.
* **Parameters:**
**eval_key** – an evaluation key
* **Returns:**
an [`fiftyone.core.evaluation.EvaluationInfo`](fiftyone.core.evaluation.md#fiftyone.core.evaluation.EvaluationInfo)
#### get_field(path, ftype=None, embedded_doc_type=None, subfield=None, read_only=None, include_private=False, leaf=False)
Returns the field instance of the provided path, or `None` if one
does not exist.
* **Parameters:**
* **path** – a field path
* **ftype** (*None*) – an optional field type or iterable of types to
enforce. Must be subclass(es) of
[`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
* **embedded_doc_type** (*None*) – an optional embedded document type or
iterable of types to enforce. Must be subclass(es) of
[`fiftyone.core.odm.BaseEmbeddedDocument`](fiftyone.core.odm.md#fiftyone.core.odm.BaseEmbeddedDocument)
* **subfield** (*None*) – an optional subfield type or iterable of subfield
types to enforce. Must be subclass(es) of
[`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
* **read_only** (*None*) – whether to optionally enforce that the field is
read-only (True) or not read-only (False)
* **include_private** (*False*) – whether to include fields that start with
`_` in the returned schema
* **leaf** (*False*) – whether to return the subfield of list fields
* **Returns:**
a [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field) instance or `None`
* **Raises:**
**ValueError** – if the field does not match provided constraints
#### get_field_schema(ftype=None, embedded_doc_type=None, subfield=None, read_only=None, info_keys=None, created_after=None, include_private=False, flat=False, unwind=True, mode=None)
Returns a schema dictionary describing the fields of the samples in
the view.
* **Parameters:**
* **ftype** (*None*) – an optional field type or iterable of types to which
to restrict the returned schema. Must be subclass(es) of
[`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
* **embedded_doc_type** (*None*) – an optional embedded document type or
iterable of types to which to restrict the returned schema.
Must be subclass(es) of
[`fiftyone.core.odm.BaseEmbeddedDocument`](fiftyone.core.odm.md#fiftyone.core.odm.BaseEmbeddedDocument)
* **subfield** (*None*) – an optional subfield type or iterable of subfield
types to which to restrict the returned schema. Must be
subclass(es) of [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
* **read_only** (*None*) – whether to restrict to (True) or exclude (False)
read-only fields. By default, all fields are included
* **info_keys** (*None*) – an optional key or list of keys that must be in
the field’s `info` dict
* **created_after** (*None*) – an optional `datetime` specifying a minimum
creation date
* **include_private** (*False*) – whether to include fields that start with
`_` in the returned schema
* **flat** (*False*) – whether to return a flattened schema where all
embedded document fields are included as top-level keys
* **unwind** (*True*) – whether to traverse into list fields. Only
applicable when `flat=True`
* **mode** (*None*) – whether to apply the above constraints before and/or
after flattening the schema. Only applicable when `flat=True`.
Supported values are `("before", "after", "both")`. The
default is `"after"`
* **Returns:**
a dict mapping field names to [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
instances
#### get_frame_field_schema(ftype=None, embedded_doc_type=None, subfield=None, read_only=None, info_keys=None, created_after=None, include_private=False, flat=False, unwind=True, mode=None)
Returns a schema dictionary describing the fields of the frames of
the samples in the view.
Only applicable for views that contain videos.
* **Parameters:**
* **ftype** (*None*) – an optional field type or iterable of types to which
to restrict the returned schema. Must be subclass(es) of
[`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
* **embedded_doc_type** (*None*) – an optional embedded document type or
iterable of types to which to restrict the returned schema.
Must be subclass(es) of
[`fiftyone.core.odm.BaseEmbeddedDocument`](fiftyone.core.odm.md#fiftyone.core.odm.BaseEmbeddedDocument)
* **subfield** (*None*) – an optional subfield type or iterable of subfield
types to which to restrict the returned schema. Must be
subclass(es) of [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
* **read_only** (*None*) – whether to restrict to (True) or exclude (False)
read-only fields. By default, all fields are included
* **info_keys** (*None*) – an optional key or list of keys that must be in
the field’s `info` dict
* **created_after** (*None*) – an optional `datetime` specifying a minimum
creation date
* **include_private** (*False*) – whether to include fields that start with
`_` in the returned schema
* **flat** (*False*) – whether to return a flattened schema where all
embedded document fields are included as top-level keys
* **unwind** (*True*) – whether to traverse into list fields. Only
applicable when `flat=True`
* **mode** (*None*) – whether to apply the above constraints before and/or
after flattening the schema. Only applicable when `flat=True`.
Supported values are `("before", "after", "both")`. The
default is `"after"`
* **Returns:**
a dict mapping field names to [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
instances, or `None` if the view does not contain videos
#### get_group(group_id, group_slices=None)
Returns a dict containing the samples for the given group ID.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("quickstart-groups")
view = dataset.select_fields()
group_id = view.take(1).first().group.id
group = view.get_group(group_id)
print(group.keys())
# ['left', 'right', 'pcd']
```
* **Parameters:**
* **group_id** – a group ID
* **group_slices** (*None*) – an optional subset of group slices to load
* **Returns:**
a dict mapping group names to
[`fiftyone.core.sample.SampleView`](fiftyone.core.sample.md#fiftyone.core.sample.SampleView) instances
* **Raises:**
**KeyError** – if the group ID is not found
#### get_index_information(include_stats=False, \_keep_index_names=False)
Returns a dictionary of information about the indexes on this
collection.
See [`pymongo.collection.Collection.index_information()`](https://pymongo.readthedocs.io/en/stable/api/pymongo/collection.html#pymongo.collection.Collection.index_information) for
details on the structure of this dictionary.
* **Parameters:**
**include_stats** (*False*) – whether to include the size, usage, and
build status of each index
* **Returns:**
a dict mapping index names to info dicts
#### get_mask_targets(field)
Gets the mask targets for the given field, or None if no mask
targets are available.
Mask targets are first retrieved from [`mask_targets()`](#fiftyone.core.clips.ClipsView.mask_targets) if they
exist, otherwise from [`default_mask_targets()`](#fiftyone.core.clips.ClipsView.default_mask_targets).
* **Parameters:**
**field** – a field name
* **Returns:**
a list of classes, or None
#### get_run_info(run_key)
Returns information about the run with the given key on this
collection.
* **Parameters:**
**run_key** – a run key
* **Returns:**
a [`fiftyone.core.runs.RunInfo`](fiftyone.core.runs.md#fiftyone.core.runs.RunInfo)
#### get_skeleton(field)
Gets the keypoint skeleton for the given field, or None if no
skeleton is available.
Skeletons are first retrieved from [`skeletons()`](#fiftyone.core.clips.ClipsView.skeletons) if they exist,
otherwise from [`default_skeleton()`](#fiftyone.core.clips.ClipsView.default_skeleton).
* **Parameters:**
**field** – a field name
* **Returns:**
a list of classes, or None
#### group_by(field_or_expr, order_by=None, reverse=False, flat=False, match_expr=None, sort_expr=None, create_index=False, order_by_key=None)
Creates a view that groups the samples in the 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
#
view = dataset.take(1000).group_by("ground_truth.label")
for group in view.iter_dynamic_groups():
group_value = group.first().ground_truth.label
print("%s: %d" % (group_value, len(group)))
#
# Variation of above operation that arranges the groups in
# decreasing order of size and immediately flattens them
#
from itertools import groupby
view = dataset.take(1000).group_by(
"ground_truth.label",
flat=True,
sort_expr=F().length(),
reverse=True,
)
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 both to `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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* group_field
The group field of the view, or None if the view is not grouped.
#### *property* group_media_types
A dict mapping group slices to media types, or None if the view is
not grouped.
#### *property* group_slice
The current group slice of the view, or None if the view is not
grouped.
#### *property* group_slices
The list of group slices of the view, or None if the view is not
grouped.
#### has_annotation_run(anno_key)
Whether this collection has an annotation run with the given key.
* **Parameters:**
**anno_key** – an annotation key
* **Returns:**
True/False
#### *property* has_annotation_runs
Whether this collection has any annotation runs.
#### has_brain_run(brain_key)
Whether this collection has a brain method run with the given key.
* **Parameters:**
**brain_key** – a brain key
* **Returns:**
True/False
#### *property* has_brain_runs
Whether this collection has any brain runs.
#### has_classes(field)
Determines whether this collection has a classes list for the given
field.
Classes may be defined either in [`classes()`](#fiftyone.core.clips.ClipsView.classes) or
[`default_classes()`](#fiftyone.core.clips.ClipsView.default_classes).
* **Parameters:**
**field** – a field name
* **Returns:**
True/False
#### has_evaluation(eval_key)
Whether this collection has an evaluation with the given key.
* **Parameters:**
**eval_key** – an evaluation key
* **Returns:**
True/False
#### *property* has_evaluations
Whether this collection has any evaluation results.
#### has_field(path)
Determines whether the collection has a field with the given name.
* **Parameters:**
**path** – the field name or `embedded.field.name`
* **Returns:**
True/False
#### has_frame_field(path)
Determines whether the collection has a frame-level field with the
given name.
* **Parameters:**
**path** – the field name or `embedded.field.name`
* **Returns:**
True/False
#### has_mask_targets(field)
Determines whether this collection has mask targets for the given
field.
Mask targets may be defined either in [`mask_targets()`](#fiftyone.core.clips.ClipsView.mask_targets) or
[`default_mask_targets()`](#fiftyone.core.clips.ClipsView.default_mask_targets).
* **Parameters:**
**field** – a field name
* **Returns:**
True/False
#### has_run(run_key)
Whether this collection has a run with the given key.
* **Parameters:**
**run_key** – a run key
* **Returns:**
True/False
#### *property* has_runs
Whether this collection has any runs.
#### has_sample_field(path)
Determines whether the collection has a sample field with the given
name.
* **Parameters:**
**path** – the field name or `embedded.field.name`
* **Returns:**
True/False
#### has_skeleton(field)
Determines whether this collection has a keypoint skeleton for the
given field.
Keypoint skeletons may be defined either in [`skeletons()`](#fiftyone.core.clips.ClipsView.skeletons) or
[`default_skeleton()`](#fiftyone.core.clips.ClipsView.default_skeleton).
* **Parameters:**
**field** – a field name
* **Returns:**
True/False
#### head(num_samples=3)
Returns a list of the first few samples in the collection.
If fewer than `num_samples` samples are in the collection, only
the available samples are returned.
* **Parameters:**
**num_samples** (*3*) – the number of samples
* **Returns:**
a list of [`fiftyone.core.sample.Sample`](fiftyone.core.sample.md#fiftyone.core.sample.Sample) objects
#### histogram_values(field_or_expr, expr=None, bins=None, range=None, auto=False)
Computes a histogram of the field values in the collection.
This aggregation is typically applied to *numeric* field types (or
lists of such types):
- [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField)
- [`fiftyone.core.fields.FloatField`](fiftyone.core.fields.md#fiftyone.core.fields.FloatField)
Examples:
```default
import numpy as np
import matplotlib.pyplot as plt
import fiftyone as fo
from fiftyone import ViewField as F
samples = []
for idx in range(100):
samples.append(
fo.Sample(
filepath="/path/to/image%d.png" % idx,
numeric_field=np.random.randn(),
numeric_list_field=list(np.random.randn(10)),
)
)
dataset = fo.Dataset()
dataset.add_samples(samples)
def plot_hist(counts, edges):
counts = np.asarray(counts)
edges = np.asarray(edges)
left_edges = edges[:-1]
widths = edges[1:] - edges[:-1]
plt.bar(left_edges, counts, width=widths, align="edge")
#
# Compute a histogram of a numeric field
#
counts, edges, other = dataset.histogram_values(
"numeric_field", bins=50, range=(-4, 4)
)
plot_hist(counts, edges)
plt.show(block=False)
#
# Compute the histogram of a numeric list field
#
counts, edges, other = dataset.histogram_values(
"numeric_list_field", bins=50
)
plot_hist(counts, edges)
plt.show(block=False)
#
# Compute the histogram of a transformation of a numeric field
#
counts, edges, other = dataset.histogram_values(
2 * (F("numeric_field") + 1), bins=50
)
plot_hist(counts, edges)
plt.show(block=False)
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate. This can also
be a list or tuple of such arguments, in which case a tuple of
corresponding aggregation results (each receiving the same
additional keyword arguments, if any) will be returned
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **bins** (*None*) – can be either an integer number of bins to generate or
a monotonically increasing sequence specifying the bin edges to
use. By default, 10 bins are created. If `bins` is an integer
and no `range` is specified, bin edges are automatically
distributed in an attempt to evenly distribute the counts in
each bin
* **range** (*None*) – a `(lower, upper)` tuple specifying a range in
which to generate equal-width bins. Only applicable when
`bins` is an integer
* **auto** (*False*) – whether to automatically choose bin edges in an
attempt to evenly distribute the counts in each bin. If this
option is chosen, `bins` will only be used if it is an
integer, and the `range` parameter is ignored
* **Returns:**
a tuple of
- counts: a list of counts in each bin
- edges: an increasing list of bin edges of length
`len(counts) + 1`. Note that each bin is treated as having an
inclusive lower boundary and exclusive upper boundary,
`[lower, upper)`, including the rightmost bin
- other: the number of items outside the bins
#### *property* info
The info dict of the underlying dataset.
See [`fiftyone.core.dataset.Dataset.info()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.info) for more information.
#### init_run(\*\*kwargs)
Initializes a config instance for a new run.
* **Parameters:**
**\*\*kwargs** – JSON serializable config parameters
* **Returns:**
a [`fiftyone.core.runs.RunConfig`](fiftyone.core.runs.md#fiftyone.core.runs.RunConfig)
#### init_run_results(run_key, \*\*kwargs)
Initializes a results instance for the run with the given key.
* **Parameters:**
* **run_key** – a run key
* **\*\*kwargs** – JSON serializable data
* **Returns:**
a [`fiftyone.core.runs.RunResults`](fiftyone.core.runs.md#fiftyone.core.runs.RunResults)
#### iter_dynamic_groups(progress=False)
Returns an iterator over the dynamic groups in the view.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("cifar10", split="test")
view = dataset.take(1000).group_by("ground_truth.label")
for group in view.iter_dynamic_groups():
group_value = group.first().ground_truth.label
print("%s: %d" % (group_value, len(group)))
```
* **Parameters:**
**progress** (*False*) – whether to render a progress bar (True/False),
use the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **Returns:**
an iterator that emits `DatasetView` instances, one per
group
#### iter_groups(group_slices=None, progress=False, autosave=False, batch_size=None, batching_strategy=None)
Returns an iterator over the groups in the view.
Examples:
```default
import random as r
import string as s
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("quickstart-groups")
view = dataset.select_fields()
def make_label():
return "".join(r.choice(s.ascii_letters) for i in range(10))
# No save context
for group in view.iter_groups(progress=True):
for sample in group.values():
sample["test"] = make_label()
sample.save()
# Save using default batching strategy
for group in view.iter_groups(progress=True, autosave=True):
for sample in group.values():
sample["test"] = make_label()
# Save in batches of 10
for group in view.iter_groups(
progress=True, autosave=True, batch_size=10
):
for sample in group.values():
sample["test"] = make_label()
# Save every 0.5 seconds
for group in view.iter_groups(
progress=True, autosave=True, batch_size=0.5
):
for sample in group.values():
sample["test"] = make_label()
```
* **Parameters:**
* **group_slices** (*None*) – an optional subset of group slices to load
* **progress** (*False*) – whether to render a progress bar (True/False),
use the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **autosave** (*False*) – whether to automatically save changes to samples
emitted by this iterator
* **batch_size** (*None*) – the batch size to use when autosaving samples.
If a `batching_strategy` is provided, this parameter
configures the strategy as described below. If no
`batching_strategy` is provided, this can either be an
integer specifying the number of samples to save in a batch
(in which case `batching_strategy` is implicitly set to
`"static"`) or a float number of seconds between batched
saves (in which case `batching_strategy` is implicitly set to
`"latency"`)
* **batching_strategy** (*None*) –
the batching strategy to use for each
save operation when autosaving samples. Supported values are:
- `"static"`: a fixed sample batch size for each save
- `"size"`: a target batch size, in bytes, for each save
- `"latency"`: a target latency, in seconds, between saves
By default, `fo.config.default_batcher` is used
* **Returns:**
an iterator that emits dicts mapping slice names to
[`fiftyone.core.sample.SampleView`](fiftyone.core.sample.md#fiftyone.core.sample.SampleView) instances, one per group
#### iter_samples(progress=False, autosave=False, batch_size=None, batching_strategy=None)
Returns an iterator over the samples in the view.
Examples:
```default
import random as r
import string as s
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("cifar10", split="test")
view = dataset.shuffle().limit(5000)
def make_label():
return "".join(r.choice(s.ascii_letters) for i in range(10))
# No save context
for sample in view.iter_samples(progress=True):
sample.ground_truth.label = make_label()
sample.save()
# Save using default batching strategy
for sample in view.iter_samples(progress=True, autosave=True):
sample.ground_truth.label = make_label()
# Save in batches of 10
for sample in view.iter_samples(
progress=True, autosave=True, batch_size=10
):
sample.ground_truth.label = make_label()
# Save every 0.5 seconds
for sample in view.iter_samples(
progress=True, autosave=True, batch_size=0.5
):
sample.ground_truth.label = make_label()
```
* **Parameters:**
* **progress** (*False*) – whether to render a progress bar (True/False),
use the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **autosave** (*False*) – whether to automatically save changes to samples
emitted by this iterator
* **batch_size** (*None*) – the batch size to use when autosaving samples.
If a `batching_strategy` is provided, this parameter
configures the strategy as described below. If no
`batching_strategy` is provided, this can either be an
integer specifying the number of samples to save in a batch
(in which case `batching_strategy` is implicitly set to
`"static"`) or a float number of seconds between batched
saves (in which case `batching_strategy` is implicitly set to
`"latency"`)
* **batching_strategy** (*None*) –
the batching strategy to use for each
save operation when autosaving samples. Supported values are:
- `"static"`: a fixed sample batch size for each save
- `"size"`: a target batch size, in bytes, for each save
- `"latency"`: a target latency, in seconds, between saves
By default, `fo.config.default_batcher` is used
* **Returns:**
an iterator over [`fiftyone.core.sample.SampleView`](fiftyone.core.sample.md#fiftyone.core.sample.SampleView) instances
#### keep_frames()
For each sample in the view, deletes all frames labels that are
**not** in the view from the underlying dataset.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### last()
Returns the last sample in the collection.
* **Returns:**
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)
#### limit(limit)
Returns 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
#
view = dataset.limit(2)
```
* **Parameters:**
**limit** – the maximum number of samples to return. If a non-positive
number is provided, an empty view is returned
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### limit_labels(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 the 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
#
view = dataset.limit_labels("predictions", 1)
```
* **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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *classmethod* list_aggregations()
Returns a list of all available methods on this collection that
apply [`fiftyone.core.aggregations.Aggregation`](fiftyone.core.aggregations.md#fiftyone.core.aggregations.Aggregation) operations to
this collection.
* **Returns:**
a list of `SampleCollection` method names
#### list_annotation_runs(type=None, method=None, \*\*kwargs)
Returns a list of annotation keys on this collection.
* **Parameters:**
* **type** (*None*) –
a specific annotation run type to match, which can be:
- a string
`fiftyone.core.annotations.AnnotationMethodConfig.type`
- a `fiftyone.core.annotations.AnnotationMethod` class
or its fully-qualified class name string
* **method** (*None*) – a specific
`fiftyone.core.annotations.AnnotationMethodConfig.method`
string to match
* **\*\*kwargs** – optional config parameters to match
* **Returns:**
a list of annotation keys
#### list_brain_runs(type=None, method=None, \*\*kwargs)
Returns a list of brain keys on this collection.
* **Parameters:**
* **type** (*None*) –
a specific brain run type to match, which can be:
- a string [`fiftyone.core.brain.BrainMethodConfig.type`](fiftyone.core.brain.md#fiftyone.core.brain.BrainMethodConfig.type)
- a [`fiftyone.core.brain.BrainMethod`](fiftyone.core.brain.md#fiftyone.core.brain.BrainMethod) class or its
fully-qualified class name string
* **method** (*None*) – a specific
[`fiftyone.core.brain.BrainMethodConfig.method`](fiftyone.core.brain.md#fiftyone.core.brain.BrainMethodConfig.method) string to
match
* **\*\*kwargs** – optional config parameters to match
* **Returns:**
a list of brain keys
#### list_evaluations(type=None, method=None, \*\*kwargs)
Returns a list of evaluation keys on this collection.
* **Parameters:**
* **type** (*None*) –
a specific evaluation type to match, which can be:
- a string
`fiftyone.core.evaluations.EvaluationMethodConfig.type`
- a `fiftyone.core.evaluations.EvaluationMethod` class
or its fully-qualified class name string
* **method** (*None*) – a specific
`fiftyone.core.evaluations.EvaluationMethodConfig.method`
string to match
* **\*\*kwargs** – optional config parameters to match
* **Returns:**
a list of evaluation keys
#### list_indexes()
Returns the list of index names on this collection.
Single-field indexes are referenced by their field name, while compound
indexes are referenced by more complicated strings. See
[`pymongo.collection.Collection.index_information()`](https://pymongo.readthedocs.io/en/stable/api/pymongo/collection.html#pymongo.collection.Collection.index_information) for
details on the compound format.
* **Returns:**
the list of index names
#### list_runs(\*\*kwargs)
Returns a list of run keys on this collection.
* **Parameters:**
**\*\*kwargs** – optional config parameters to match
* **Returns:**
a list of run keys
#### list_schema(field_or_expr, expr=None)
Extracts the value type(s) in a specified list field across all
samples in the collection.
Examples:
```default
from datetime import datetime
import fiftyone as fo
dataset = fo.Dataset()
sample1 = fo.Sample(
filepath="image1.png",
ground_truth=fo.Classification(
label="cat",
info=[
fo.DynamicEmbeddedDocument(
task="initial_annotation",
author="Alice",
timestamp=datetime(1970, 1, 1),
notes=["foo", "bar"],
),
fo.DynamicEmbeddedDocument(
task="editing_pass",
author="Bob",
timestamp=datetime.utcnow(),
),
],
),
)
sample2 = fo.Sample(
filepath="image2.png",
ground_truth=fo.Classification(
label="dog",
info=[
fo.DynamicEmbeddedDocument(
task="initial_annotation",
author="Bob",
timestamp=datetime(2018, 10, 18),
notes=["spam", "eggs"],
),
],
),
)
dataset.add_samples([sample1, sample2])
# Determine that `ground_truth.info` contains embedded documents
print(dataset.list_schema("ground_truth.info"))
# fo.EmbeddedDocumentField
# Determine the fields of the embedded documents in the list
print(dataset.schema("ground_truth.info[]"))
# {'task': StringField, ..., 'notes': ListField}
# Determine the type of the values in the nested `notes` list field
# Since `ground_truth.info` is not yet declared on the dataset's
# schema, we must manually include `[]` to unwind the info lists
print(dataset.list_schema("ground_truth.info[].notes"))
# fo.StringField
# Declare the `ground_truth.info` field
dataset.add_sample_field(
"ground_truth.info",
fo.ListField,
subfield=fo.EmbeddedDocumentField,
embedded_doc_type=fo.DynamicEmbeddedDocument,
)
# Now we can inspect the nested `notes` field without unwinding
print(dataset.list_schema("ground_truth.info.notes"))
# fo.StringField
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **Returns:**
a [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field) or list of
[`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field) instances describing the value
type(s) in the list
#### *classmethod* list_view_stages()
Returns a list of all available methods on this collection that
apply [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage) operations to this
collection.
* **Returns:**
a list of `SampleCollection` method names
#### load_annotation_results(anno_key, cache=True, \*\*kwargs)
Loads the results for the annotation run with the given key on this
collection.
The [`fiftyone.utils.annotations.AnnotationResults`](fiftyone.utils.annotations.md#fiftyone.utils.annotations.AnnotationResults) object
returned by this method will provide a variety of backend-specific
methods allowing you to perform actions such as checking the status and
deleting this run from the annotation backend.
Use [`load_annotations()`](#fiftyone.core.clips.ClipsView.load_annotations) to load the labels from an annotation
run onto your FiftyOne dataset.
* **Parameters:**
* **anno_key** – an annotation key
* **cache** (*True*) – whether to cache the results on the collection
* **\*\*kwargs** – keyword arguments for run’s
[`fiftyone.core.annotation.AnnotationMethodConfig.load_credentials()`](fiftyone.core.annotation.md#fiftyone.core.annotation.AnnotationMethodConfig.load_credentials)
method
* **Returns:**
a [`fiftyone.utils.annotations.AnnotationResults`](fiftyone.utils.annotations.md#fiftyone.utils.annotations.AnnotationResults)
#### load_annotation_view(anno_key, select_fields=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) on which the
specified annotation run was performed on this collection.
* **Parameters:**
* **anno_key** – an annotation key
* **select_fields** (*False*) – whether to exclude fields involved in other
annotation runs
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### load_annotations(anno_key, dest_field=None, unexpected='prompt', cleanup=False, progress=None, \*\*kwargs)
Downloads the labels from the given annotation run from the
annotation backend and merges them into this collection.
See [this page](../integrations/annotation.md#loading-annotations) for more information
about using this method to import annotations that you have scheduled
by calling [`annotate()`](#fiftyone.core.clips.ClipsView.annotate).
* **Parameters:**
* **anno_key** – an annotation key
* **dest_field** (*None*) – an optional name of a new destination field
into which to load the annotations, or a dict mapping field names
in the run’s label schema to new destination field names
* **unexpected** ( *"prompt"*) –
how to deal with any unexpected labels that
don’t match the run’s label schema when importing. The
supported values are:
- `"prompt"`: present an interactive prompt to
direct/discard unexpected labels
- `"ignore"`: automatically ignore any unexpected labels
- `"keep"`: automatically keep all unexpected labels in a
field whose name matches the label type
- `"return"`: return a dict containing all unexpected
labels, or `None` if there aren’t any
* **cleanup** (*False*) – whether to delete any information regarding this
run from the annotation backend after loading the annotations
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **\*\*kwargs** – keyword arguments for the run’s
[`fiftyone.core.annotation.AnnotationMethodConfig.load_credentials()`](fiftyone.core.annotation.md#fiftyone.core.annotation.AnnotationMethodConfig.load_credentials)
method
* **Returns:**
`None`, unless `unexpected=="return"` and unexpected labels are
found, in which case a dict containing the extra labels is returned
#### load_brain_results(brain_key, cache=True, load_view=True, \*\*kwargs)
Loads the results for the brain method run with the given key on
this collection.
* **Parameters:**
* **brain_key** – a brain key
* **cache** (*True*) – whether to cache the results on the collection
* **load_view** (*True*) – whether to load the view on which the results
were computed (True) or the full dataset (False)
* **\*\*kwargs** – keyword arguments for the run’s
[`fiftyone.core.brain.BrainMethodConfig.load_credentials()`](fiftyone.core.brain.md#fiftyone.core.brain.BrainMethodConfig.load_credentials)
method
* **Returns:**
a [`fiftyone.core.brain.BrainResults`](fiftyone.core.brain.md#fiftyone.core.brain.BrainResults)
#### load_brain_view(brain_key, select_fields=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) on which the
specified brain method run was performed on this collection.
* **Parameters:**
* **brain_key** – a brain key
* **select_fields** (*False*) – whether to exclude fields involved in other
brain method runs
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### load_evaluation_results(eval_key, cache=True, \*\*kwargs)
Loads the results for the evaluation with the given key on this
collection.
* **Parameters:**
* **eval_key** – an evaluation key
* **cache** (*True*) – whether to cache the results on the collection
* **\*\*kwargs** – keyword arguments for the run’s
[`fiftyone.core.evaluation.EvaluationMethodConfig.load_credentials()`](fiftyone.core.evaluation.md#fiftyone.core.evaluation.EvaluationMethodConfig.load_credentials)
method
* **Returns:**
a [`fiftyone.core.evaluation.EvaluationResults`](fiftyone.core.evaluation.md#fiftyone.core.evaluation.EvaluationResults)
#### load_evaluation_view(eval_key, select_fields=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) on which the
specified evaluation was performed on this collection.
* **Parameters:**
* **eval_key** – an evaluation key
* **select_fields** (*False*) – whether to exclude fields involved in other
evaluations
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### load_run_results(run_key, cache=True, load_view=True, \*\*kwargs)
Loads the results for the run with the given key on this collection.
* **Parameters:**
* **run_key** – a run key
* **cache** (*True*) – whether to cache the results on the collection
* **load_view** (*True*) – whether to load the view on which the results
were computed (True) or the full dataset (False)
* **\*\*kwargs** – keyword arguments for the run’s
[`fiftyone.core.runs.RunConfig.load_credentials()`](fiftyone.core.runs.md#fiftyone.core.runs.RunConfig.load_credentials) method
* **Returns:**
a [`fiftyone.core.runs.RunResults`](fiftyone.core.runs.md#fiftyone.core.runs.RunResults)
#### load_run_view(run_key, select_fields=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) on which the
specified run was performed on this collection.
* **Parameters:**
* **run_key** – a run key
* **select_fields** (*False*) – whether to exclude fields involved in other
runs
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### make_unique_field_name(root='')
Makes a unique field name with the given root name for the
collection.
* **Parameters:**
**root** – an optional root for the output field name
* **Returns:**
the field name
#### map_labels(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 the 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"
#
view = dataset.map_labels("weather", {"partly cloudy": "cloudy"})
#
# Map "rabbit" and "squirrel" predictions to "other"
#
view = dataset.map_labels(
"predictions", {"rabbit": "other", "squirrel": "other"}
)
```
* **Parameters:**
* **field** – the labels field to map
* **map** – a dict mapping label values to new label values
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### map_samples(map_fcn, save=False, skip_failures=False, parallelize_method=None, num_workers=None, batch_method=None, batch_size=None, progress=None)
Applies the given function to each sample in the collection and
returns the results as a generator.
By default, a multiprocessing pool is used to parallelize the work,
unless this method is called in a daemon process (subprocess), in which
case no workers are used.
This function effectively performs the following map operation with the
outer loop in parallel:
```default
for batch_view in fou.iter_slices(sample_collection, batch_size):
for sample in batch_view.iter_samples(autosave=save):
sample_output = map_fcn(sample)
yield sample.id, sample_output
```
Example:
```default
from collections import Counter
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("cifar10", split="train")
view = dataset.select_fields("ground_truth")
def map_fcn(sample):
return sample.ground_truth.label.upper()
counter = Counter()
for _, label in view.map_samples(map_fcn):
counter[label] += 1
print(dict(counter))
```
* **Parameters:**
* **map_fcn** – a function to apply to each sample in the collection
* **save** (*False*) – whether to save any sample edits applied by
`map_fcn`
* **skip_failures** (*False*) – whether to gracefully continue without
raising an error if the update function raises an exception for
a sample
* **parallelize_method** (*None*) – the parallelization method to use.
Supported values are `{"process", "thread"}`. The default is
`fiftyone.config.default_parallelization_method`
* **num_workers** (*None*) – the number of workers to use. When using
process parallelism, this defaults to
`fiftyone.config.default_process_pool_workers` if the value
is set, else
[`fiftyone.core.utils.recommend_process_pool_workers()`](fiftyone.core.utils.md#fiftyone.core.utils.recommend_process_pool_workers)
workers are used. If this value is <= 1, all work is done in
the main process
* **batch_method** (*None*) – whether to use IDs (`"id"`) or slices
(`"slice"`) to assign samples to workers
* **batch_size** (*None*) – an optional number of samples to distribute to
each worker at a time. By default, samples are evenly
distributed to workers with one batch per worker
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead, or
“workers” to render per-worker progress bars
* **Returns:**
a generator that emits `(sample_id, map_output)` tuples
#### map_values(field, map)
Maps the values in the given field to new values for each sample in
the 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
#
view = dataset.map_values("str_field", mapping)
print(view.count_values("str_field"))
# {"animal": 200}
view = dataset.map_values("list_field", mapping)
print(view.count_values("list_field"))
# {"animal": 200}
#
# Map values in nested fields
#
view = dataset.map_values("ground_truth.detections.label", mapping)
print(view.count_values("ground_truth.detections.label"))
# {"animal": 183, ...}
view = dataset.map_values("ground_truth.detections.tags", mapping)
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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* mask_targets
The mask targets of the underlying dataset.
See [`fiftyone.core.dataset.Dataset.mask_targets()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.mask_targets) for more
information.
#### match(filter)
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"
#
view = dataset.match(F("filepath").ends_with(".jpg"))
#
# Only include samples whose `weather` field is "sunny"
#
view = dataset.match(F("weather.label") == "sunny")
#
# Only include samples with at least 2 objects in their
# `predictions` field
#
view = dataset.match(F("predictions.detections").length() >= 2)
#
# 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)
view = dataset.match(small_boxes.length() > 0)
```
* **Parameters:**
**filter** –
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 describing the filter to apply
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### match_frames(filter, omit_empty=True)
Filters the frames in the 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()
view = dataset.match_frames(num_objects > 10)
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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### match_labels(labels=None, ids=None, instance_ids=None, tags=None, filter=None, fields=None, bool=None)
Selects the samples from the collection that contain (or do not
contain) at least one label that matches the specified criteria.
Note that, unlike [`select_labels()`](#fiftyone.core.clips.ClipsView.select_labels) and [`filter_labels()`](#fiftyone.core.clips.ClipsView.filter_labels), 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...
view = dataset.match_labels(labels=session.selected_labels)
#
# 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,
]
view = dataset.match_labels(ids=ids)
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
view = dataset.match_labels(tags="test")
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
view = dataset.match_labels(filter=filter, fields="predictions")
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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### match_tags(tags, bool=None, all=False)
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
#
view = dataset.match_tags("test")
#
# Only include samples that do not have the "test" tag
#
view = dataset.match_tags("test", bool=False)
#
# Only include samples that have the "test" or "train" tags
#
view = dataset.match_tags(["test", "train"])
#
# Only include samples that have the "test" and "train" tags
#
view = dataset.match_tags(["test", "train"], all=True)
#
# Only include samples that do not have the "test" or "train" tags
#
view = dataset.match_tags(["test", "train"], bool=False)
#
# Only include samples that do not have the "test" and "train" tags
#
view = dataset.match_tags(["test", "train"], bool=False, all=True)
```
* **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 (False) of the given tags
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### max(field_or_expr, expr=None, safe=False)
Computes the maximum of a numeric field of the collection.
`None`-valued fields are ignored.
This aggregation is typically applied to *numeric* or *date* field
types (or lists of such types):
- [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField)
- [`fiftyone.core.fields.FloatField`](fiftyone.core.fields.md#fiftyone.core.fields.FloatField)
- [`fiftyone.core.fields.DateField`](fiftyone.core.fields.md#fiftyone.core.fields.DateField)
- [`fiftyone.core.fields.DateTimeField`](fiftyone.core.fields.md#fiftyone.core.fields.DateTimeField)
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",
numeric_field=1.0,
numeric_list_field=[1, 2, 3],
),
fo.Sample(
filepath="/path/to/image2.png",
numeric_field=4.0,
numeric_list_field=[1, 2],
),
fo.Sample(
filepath="/path/to/image3.png",
numeric_field=None,
numeric_list_field=None,
),
]
)
#
# Compute the maximum of a numeric field
#
max = dataset.max("numeric_field")
print(max) # the max
#
# Compute the maximum of a numeric list field
#
max = dataset.max("numeric_list_field")
print(max) # the max
#
# Compute the maximum of a transformation of a numeric field
#
max = dataset.max(2 * (F("numeric_field") + 1))
print(max) # the max
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate. This can also
be a list or tuple of such arguments, in which case a tuple of
corresponding aggregation results (each receiving the same
additional keyword arguments, if any) will be returned
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **safe** (*False*) – whether to ignore nan/inf values when dealing with
floating point values
* **Returns:**
the maximum value
#### mean(field_or_expr, expr=None, safe=False)
Computes the arithmetic mean of the field values of the collection.
`None`-valued fields are ignored.
This aggregation is typically applied to *numeric* field types (or
lists of such types):
- [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField)
- [`fiftyone.core.fields.FloatField`](fiftyone.core.fields.md#fiftyone.core.fields.FloatField)
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",
numeric_field=1.0,
numeric_list_field=[1, 2, 3],
),
fo.Sample(
filepath="/path/to/image2.png",
numeric_field=4.0,
numeric_list_field=[1, 2],
),
fo.Sample(
filepath="/path/to/image3.png",
numeric_field=None,
numeric_list_field=None,
),
]
)
#
# Compute the mean of a numeric field
#
mean = dataset.mean("numeric_field")
print(mean) # the mean
#
# Compute the mean of a numeric list field
#
mean = dataset.mean("numeric_list_field")
print(mean) # the mean
#
# Compute the mean of a transformation of a numeric field
#
mean = dataset.mean(2 * (F("numeric_field") + 1))
print(mean) # the mean
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate. This can also
be a list or tuple of such arguments, in which case a tuple of
corresponding aggregation results (each receiving the same
additional keyword arguments, if any) will be returned
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **safe** (*False*) – whether to ignore nan/inf values when dealing with
floating point values
* **Returns:**
the mean
#### merge_labels(in_field, out_field)
Merges the labels from the given input field into the given output
field of the collection.
If this collection is a dataset, the input field is deleted after the
merge.
If this collection is a view, the input field will still exist on the
underlying dataset but will only contain the labels not present in this
view.
* **Parameters:**
* **in_field** – the name of the input label field
* **out_field** – the name of the output label field, which will be
created if necessary
#### min(field_or_expr, expr=None, safe=False)
Computes the minimum of a numeric field of the collection.
`None`-valued fields are ignored.
This aggregation is typically applied to *numeric* or *date* field
types (or lists of such types):
- [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField)
- [`fiftyone.core.fields.FloatField`](fiftyone.core.fields.md#fiftyone.core.fields.FloatField)
- [`fiftyone.core.fields.DateField`](fiftyone.core.fields.md#fiftyone.core.fields.DateField)
- [`fiftyone.core.fields.DateTimeField`](fiftyone.core.fields.md#fiftyone.core.fields.DateTimeField)
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",
numeric_field=1.0,
numeric_list_field=[1, 2, 3],
),
fo.Sample(
filepath="/path/to/image2.png",
numeric_field=4.0,
numeric_list_field=[1, 2],
),
fo.Sample(
filepath="/path/to/image3.png",
numeric_field=None,
numeric_list_field=None,
),
]
)
#
# Compute the minimum of a numeric field
#
min = dataset.min("numeric_field")
print(min) # the min
#
# Compute the minimum of a numeric list field
#
min = dataset.min("numeric_list_field")
print(min) # the min
#
# Compute the minimum of a transformation of a numeric field
#
min = dataset.min(2 * (F("numeric_field") + 1))
print(min) # the min
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate. This can also
be a list or tuple of such arguments, in which case a tuple of
corresponding aggregation results (each receiving the same
additional keyword arguments, if any) will be returned
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **safe** (*False*) – whether to ignore nan/inf values when dealing with
floating point values
* **Returns:**
the minimum value
#### mongo(pipeline, \_needs_frames=None, \_group_slices=None)
Adds 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
#
view = dataset.mongo([{"$skip": 1}, {"$limit": 2}])
#
# Sort by the number of objects in the `precictions` field
#
view = dataset.mongo([
{
"$addFields": {
"_sort_field": {
"$size": {"$ifNull": ["$predictions.detections", []]}
}
}
},
{"$sort": {"_sort_field": -1}},
{"$project": {"_sort_field": False}},
])
```
* **Parameters:**
**pipeline** – a MongoDB aggregation pipeline (list of dicts)
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### one(expr, exact=False)
Returns a single sample in this collection matching the expression.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
#
# Get a sample by filepath
#
# A random filepath in the dataset
filepath = dataset.take(1).first().filepath
# Get sample by filepath
sample = dataset.one(F("filepath") == filepath)
#
# Dealing with multiple matches
#
# Get a sample whose image is JPEG
sample = dataset.one(F("filepath").ends_with(".jpg"))
# Raises an error since there are multiple JPEGs
dataset.one(F("filepath").ends_with(".jpg"), exact=True)
```
* **Parameters:**
* **expr** –
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 evaluates to `True` for the sample to match
* **exact** (*False*) – whether to raise an error if multiple samples match
the expression
* **Raises:**
* **ValueError** – if no samples match the expression or if `exact=True`
* **and multiple samples match the expression** –
* **Returns:**
a [`fiftyone.core.sample.SampleView`](fiftyone.core.sample.md#fiftyone.core.sample.SampleView)
#### quantiles(field_or_expr, quantiles, expr=None, safe=False)
Computes the quantile(s) of the field values of a collection.
`None`-valued fields are ignored.
This aggregation is typically applied to *numeric* field types (or
lists of such types):
- [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField)
- [`fiftyone.core.fields.FloatField`](fiftyone.core.fields.md#fiftyone.core.fields.FloatField)
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",
numeric_field=1.0,
numeric_list_field=[1, 2, 3],
),
fo.Sample(
filepath="/path/to/image2.png",
numeric_field=4.0,
numeric_list_field=[1, 2],
),
fo.Sample(
filepath="/path/to/image3.png",
numeric_field=None,
numeric_list_field=None,
),
]
)
#
# Compute the quantiles of a numeric field
#
quantiles = dataset.quantiles("numeric_field", [0.1, 0.5, 0.9])
print(quantiles) # the quantiles
#
# Compute the quantiles of a numeric list field
#
quantiles = dataset.quantiles("numeric_list_field", [0.1, 0.5, 0.9])
print(quantiles) # the quantiles
#
# Compute the mean of a transformation of a numeric field
#
quantiles = dataset.quantiles(2 * (F("numeric_field") + 1), [0.1, 0.5, 0.9])
print(quantiles) # the quantiles
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate
* **quantiles** – the quantile or iterable of quantiles to compute. Each
quantile must be a numeric value in `[0, 1]`
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **safe** (*False*) – whether to ignore nan/inf values when dealing with
floating point values
* **Returns:**
the quantile or list of quantiles
#### register_run(run_key, config, results=None, overwrite=False, cleanup=True, cache=True)
Registers a run under the given key on this collection.
* **Parameters:**
* **run_key** – a run key
* **config** – a [`fiftyone.core.runs.RunConfig`](fiftyone.core.runs.md#fiftyone.core.runs.RunConfig)
* **results** (*None*) – an optional [`fiftyone.core.runs.RunResults`](fiftyone.core.runs.md#fiftyone.core.runs.RunResults)
* **overwrite** (*False*) – whether to allow overwriting an existing run of
the same type
* **cleanup** (*True*) – whether to execute an existing run’s
[`fiftyone.core.runs.Run.cleanup()`](fiftyone.core.runs.md#fiftyone.core.runs.Run.cleanup) method when overwriting
it
* **cache** (*True*) – whether to cache the results on the collection
#### rename_annotation_run(anno_key, new_anno_key)
Replaces the key for the given annotation run with a new key.
* **Parameters:**
* **anno_key** – an annotation key
* **new_anno_key** – a new annotation key
#### rename_brain_run(brain_key, new_brain_key)
Replaces the key for the given brain run with a new key.
* **Parameters:**
* **brain_key** – a brain key
* **new_brain_key** – a new brain key
#### rename_evaluation(eval_key, new_eval_key)
Replaces the key for the given evaluation with a new key.
* **Parameters:**
* **eval_key** – an evaluation key
* **new_anno_key** – a new evaluation key
#### rename_run(run_key, new_run_key)
Replaces the key for the given run with a new key.
* **Parameters:**
* **run_key** – a run key
* **new_run_key** – a new run key
#### save_context(batch_size=None, batching_strategy=None)
Returns a context that can be used to save samples from this
collection according to a configurable batching strategy.
Examples:
```default
import random as r
import string as s
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("cifar10", split="test")
def make_label():
return "".join(r.choice(s.ascii_letters) for i in range(10))
# No save context
for sample in dataset.iter_samples(progress=True):
sample.ground_truth.label = make_label()
sample.save()
# Save using default batching strategy
with dataset.save_context() as context:
for sample in dataset.iter_samples(progress=True):
sample.ground_truth.label = make_label()
context.save(sample)
# Save in batches of 10
with dataset.save_context(batch_size=10) as context:
for sample in dataset.iter_samples(progress=True):
sample.ground_truth.label = make_label()
context.save(sample)
# Save every 0.5 seconds
with dataset.save_context(batch_size=0.5) as context:
for sample in dataset.iter_samples(progress=True):
sample.ground_truth.label = make_label()
context.save(sample)
```
* **Parameters:**
* **batch_size** (*None*) – the batch size to use. If a `batching_strategy`
is provided, this parameter configures the strategy as
described below. If no `batching_strategy` is provided, this
can either be an integer specifying the number of samples to
save in a batch (in which case `batching_strategy` is
implicitly set to `"static"`) or a float number of seconds
between batched saves (in which case `batching_strategy` is
implicitly set to `"latency"`)
* **batching_strategy** (*None*) –
the batching strategy to use for each
save operation. Supported values are:
- `"static"`: a fixed sample batch size for each save
- `"size"`: a target batch size, in bytes, for each save
- `"latency"`: a target latency, in seconds, between saves
By default, `fo.config.default_batcher` is used
* **Returns:**
a `SaveContext`
#### save_run_results(run_key, results, overwrite=True, cache=True)
Saves run results for the run with the given key.
* **Parameters:**
* **run_key** – a run key
* **results** – a [`fiftyone.core.runs.RunResults`](fiftyone.core.runs.md#fiftyone.core.runs.RunResults)
* **overwrite** (*True*) – whether to overwrite an existing result with the
same key
* **cache** (*True*) – whether to cache the results on the collection
#### schema(field_or_expr, expr=None, dynamic_only=False, \_doc_type=None, \_include_private=False)
Extracts the names and types of the attributes of a specified
embedded document field across all samples in the collection.
Schema aggregations are useful for detecting the presence and types of
dynamic attributes of [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) fields
across a collection.
Examples:
```default
import fiftyone as fo
dataset = fo.Dataset()
sample1 = fo.Sample(
filepath="image1.png",
ground_truth=fo.Detections(
detections=[
fo.Detection(
label="cat",
bounding_box=[0.1, 0.1, 0.4, 0.4],
foo="bar",
hello=True,
),
fo.Detection(
label="dog",
bounding_box=[0.5, 0.5, 0.4, 0.4],
hello=None,
)
]
)
)
sample2 = fo.Sample(
filepath="image2.png",
ground_truth=fo.Detections(
detections=[
fo.Detection(
label="rabbit",
bounding_box=[0.1, 0.1, 0.4, 0.4],
foo=None,
),
fo.Detection(
label="squirrel",
bounding_box=[0.5, 0.5, 0.4, 0.4],
hello="there",
),
]
)
)
dataset.add_samples([sample1, sample2])
#
# Get schema of all dynamic attributes on the detections in a
# `Detections` field
#
print(dataset.schema("ground_truth.detections", dynamic_only=True))
# {'foo': StringField, 'hello': [BooleanField, StringField]}
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **dynamic_only** (*False*) – whether to only include dynamically added
attributes
* **Returns:**
a dict mapping field names to [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
instances. If a field’s values takes multiple non-None types, the
list of observed types will be returned
#### select(sample_ids, ordered=False)
Selects the samples with the given IDs from the 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...
view = dataset.select(session.selected)
```
* **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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### select_by(field, values, ordered=False)
Selects the samples with the given field values from the 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.clips.ClipsView.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
#
view = dataset.select_by("int", [1, 51, 11, 41, 21, 31])
print(view.head(6))
#
# Create a view containing samples whose `str` field have the given
# values, in order
#
view = dataset.select_by(
"str", ["1", "51", "11", "41", "21", "31"], ordered=True
)
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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### select_fields(field_names=None, meta_filter=None, \_allow_missing=False)
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
#
view = dataset.select_fields()
#
# Include only the `uniqueness` field (and the default fields) on
# each sample
#
view = dataset.select_fields("uniqueness")
#
# Include only the `mood` attribute (and the default attributes) of
# each `Detection` in the `ground_truth` field
#
view = dataset.select_fields("ground_truth.detections.mood")
```
* **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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### select_frames(frame_ids, omit_empty=True)
Selects the frames with the given IDs from the 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,
]
view = dataset.select_frames(frame_ids)
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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### select_group_slices(slices=None, media_type=None, flat=True, \_allow_mixed=False, \_force_mixed=False)
Selects the specified group slice(s) from the 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
#
view = dataset.select_group_slices("ego")
#
# Retrieve the samples from the "left" or "right" group slices
#
view = dataset.select_group_slices(["left", "right"])
#
# Select only the "left" and "right" group slices
#
view = dataset.select_group_slices(["left", "right"], flat=False)
#
# Retrieve all image samples
#
view = dataset.select_group_slices(media_type="image")
```
* **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)
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### select_groups(group_ids, ordered=False)
Selects the groups with the given IDs from the 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")
view = dataset.select_groups(group_ids)
assert set(view.values("group.id")) == set(group_ids)
view = dataset.select_groups(group_ids, ordered=True)
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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### select_labels(labels=None, ids=None, instance_ids=None, tags=None, fields=None, omit_empty=True)
Selects only the specified labels from the 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...
view = dataset.select_labels(labels=session.selected_labels)
#
# 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,
]
view = dataset.select_labels(ids=ids)
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_label_tags())
# Retrieve the labels via their tag
view = dataset.select_labels(tags="test")
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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### set_field(field, expr, \_allow_missing=False)
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 the `uniqueness` field that are less than
# 0.5 with `None`
#
view = dataset.set_field(
"uniqueness",
(F("uniqueness") >= 0.5).if_else(F("uniqueness"), None)
)
print(view.bounds("uniqueness"))
#
# Lower bound all object confidences in the `predictions` field at
# 0.5
#
view = dataset.set_field(
"predictions.detections.confidence", F("confidence").max(0.5)
)
print(view.bounds("predictions.detections.confidence"))
#
# Add a `num_predictions` property to the `predictions` field that
# contains the number of objects in the field
#
view = dataset.set_field(
"predictions.num_predictions",
F("$predictions.detections").length(),
)
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"
]
view = dataset.set_field(
"predictions.detections.is_animal", F("label").is_in(ANIMALS)
)
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 expression](https://docs.mongodb.com/manual/meta/aggregation-quick-reference/#aggregation-expressions)
that defines the field value to set
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### shuffle(seed=None)
Randomly shuffles the samples in the 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
#
view = dataset.shuffle()
#
# Shuffle the samples with a fixed random seed
#
view = dataset.shuffle(seed=51)
```
* **Parameters:**
**seed** (*None*) – an optional random seed to use when shuffling the
samples
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* skeletons
The keypoint skeletons of the underlying dataset.
See [`fiftyone.core.dataset.Dataset.skeletons()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.skeletons) for more
information.
#### skip(skip)
Omits the given number of samples from the head of the 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
#
view = dataset.skip(2)
```
* **Parameters:**
**skip** – the number of samples to skip. If a non-positive number is
provided, no samples are omitted
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### sort_by(field_or_expr, reverse=False, create_index=False)
Sorts the samples in the 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
#
view = dataset.sort_by("uniqueness", reverse=False)
#
# 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)
view = dataset.sort_by(small_boxes.length(), reverse=True)
#
# Performs a compound sort where samples are first sorted in
# descending or by number of detections and then in ascending order
# of uniqueness for samples with the same number of predictions
#
view = dataset.sort_by(
[
(F("predictions.detections").length(), -1),
("uniqueness", 1),
]
)
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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### sort_by_similarity(query, k=None, reverse=False, dist_field=None, brain_key=None)
Sorts the 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
view = dataset.sort_by_similarity(query_id, k=5)
#
# 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)
view = dataset.sort_by_similarity(query, k=5)
#
# Sort samples by their similarity to a text prompt
#
query = "kites high in the air"
view = dataset.sort_by_similarity(query, k=5)
```
* **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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### split_labels(in_field, out_field, filter=None)
Splits the labels from the given input field into the given output
field of the collection.
This method is typically invoked on a view that has filtered the
contents of the specified input field, so that the labels in the view
are moved to the output field and the remaining labels are left
in-place.
Alternatively, you can provide a `filter` expression that selects the
labels of interest to move in this collection.
* **Parameters:**
* **in_field** – the name of the input label field
* **out_field** – the name of the output label field, which will be
created if necessary
* **filter** (*None*) – a boolean
[`fiftyone.core.expressions.ViewExpression`](fiftyone.core.expressions.md#fiftyone.core.expressions.ViewExpression) to apply to
each label in the input field to determine whether to move it
(True) or leave it (False)
#### *property* static_transforms
The static transforms of the underlying dataset.
See [`fiftyone.core.dataset.Dataset.static_transforms()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.static_transforms) for more
information.
#### stats(include_media=False, include_indexes=False, compressed=False)
Returns stats about the collection on disk.
The `samples` keys refer to the sample documents stored in the
database.
For video datasets, the `frames` keys refer to the frame documents
stored in the database.
The `media` keys refer to the raw media associated with each sample
on disk.
The `index[es]` keys refer to the indexes associated with the
dataset.
Note that dataset-level metadata such as annotation runs are not
included in this computation.
* **Parameters:**
* **include_media** (*False*) – whether to include stats about the size of
the raw media in the collection
* **include_indexes** (*False*) – whether to include stats on the dataset’s
indexes
* **compressed** (*False*) – whether to return the sizes of collections in
their compressed form on disk (True) or the logical
uncompressed size of the collections (False). This option is
only supported for datasets (not views)
* **Returns:**
a stats dict
#### std(field_or_expr, expr=None, safe=False, sample=False)
Computes the standard deviation of the field values of the
collection.
`None`-valued fields are ignored.
This aggregation is typically applied to *numeric* field types (or
lists of such types):
- [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField)
- [`fiftyone.core.fields.FloatField`](fiftyone.core.fields.md#fiftyone.core.fields.FloatField)
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",
numeric_field=1.0,
numeric_list_field=[1, 2, 3],
),
fo.Sample(
filepath="/path/to/image2.png",
numeric_field=4.0,
numeric_list_field=[1, 2],
),
fo.Sample(
filepath="/path/to/image3.png",
numeric_field=None,
numeric_list_field=None,
),
]
)
#
# Compute the standard deviation of a numeric field
#
std = dataset.std("numeric_field")
print(std) # the standard deviation
#
# Compute the standard deviation of a numeric list field
#
std = dataset.std("numeric_list_field")
print(std) # the standard deviation
#
# Compute the standard deviation of a transformation of a numeric field
#
std = dataset.std(2 * (F("numeric_field") + 1))
print(std) # the standard deviation
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate. This can also
be a list or tuple of such arguments, in which case a tuple of
corresponding aggregation results (each receiving the same
additional keyword arguments, if any) will be returned
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **safe** (*False*) – whether to ignore nan/inf values when dealing with
floating point values
* **sample** (*False*) – whether to compute the sample standard deviation rather
than the population standard deviation
* **Returns:**
the standard deviation
#### sum(field_or_expr, expr=None, safe=False)
Computes the sum of the field values of the collection.
`None`-valued fields are ignored.
This aggregation is typically applied to *numeric* field types (or
lists of such types):
- [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField)
- [`fiftyone.core.fields.FloatField`](fiftyone.core.fields.md#fiftyone.core.fields.FloatField)
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",
numeric_field=1.0,
numeric_list_field=[1, 2, 3],
),
fo.Sample(
filepath="/path/to/image2.png",
numeric_field=4.0,
numeric_list_field=[1, 2],
),
fo.Sample(
filepath="/path/to/image3.png",
numeric_field=None,
numeric_list_field=None,
),
]
)
#
# Compute the sum of a numeric field
#
total = dataset.sum("numeric_field")
print(total) # the sum
#
# Compute the sum of a numeric list field
#
total = dataset.sum("numeric_list_field")
print(total) # the sum
#
# Compute the sum of a transformation of a numeric field
#
total = dataset.sum(2 * (F("numeric_field") + 1))
print(total) # the sum
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate. This can also
be a list or tuple of such arguments, in which case a tuple of
corresponding aggregation results (each receiving the same
additional keyword arguments, if any) will be returned
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **safe** (*False*) – whether to ignore nan/inf values when dealing with
floating point values
* **Returns:**
the sum
#### summary()
Returns a string summary of the view.
* **Returns:**
a string summary
#### sync_last_modified_at(include_frames=True)
Syncs the `last_modified_at` property(s) of the dataset.
Updates the `last_modified_at` property of the dataset if
necessary to incorporate any modification/deletion timestamps to its
samples.
If `include_frames==True`, the `last_modified_at` property of
each video sample is first updated if necessary to incorporate any
modification timestamps to its frames.
* **Parameters:**
**include_frames** (*True*) – whether to update the `last_modified_at`
property of video samples. Only applicable to datasets that
contain videos
#### tag_labels(tags, label_fields=None)
Adds the tag(s) to all labels in the specified label field(s) of
this collection, if necessary.
* **Parameters:**
* **tags** – a tag or iterable of tags
* **label_fields** (*None*) – an optional name or iterable of names of
[`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) fields. By default, all
label fields are used
#### tag_samples(tags)
Adds the tag(s) to all samples in this collection, if necessary.
* **Parameters:**
**tags** – a tag or iterable of tags
#### *property* tags
The list of tags of the underlying dataset.
See [`fiftyone.core.dataset.Dataset.tags()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.tags) for more information.
#### tail(num_samples=3)
Returns a list of the last few samples in the collection.
If fewer than `num_samples` samples are in the collection, only
the available samples are returned.
* **Parameters:**
**num_samples** (*3*) – the number of samples
* **Returns:**
a list of [`fiftyone.core.sample.Sample`](fiftyone.core.sample.md#fiftyone.core.sample.Sample) objects
#### take(size, seed=None)
Randomly samples the given number of samples from the 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
#
view = dataset.take(2)
#
# Take two random samples from the dataset with a fixed seed
#
view = dataset.take(2, seed=51)
```
* **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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### to_clips(field_or_expr, \*\*kwargs)
Creates a view that contains one sample per clip defined by the
given field or expression in the 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.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
#
clips = (
dataset
.filter_labels("frames.detections", F("label") == "road sign")
.to_clips("frames.detections")
)
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")
clips = dataset.to_clips(signs.length() >= 2)
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
* **other_fields** (*None*) –
controls whether sample fields other than the
default sample fields are included. Can be any of the
following:
- a field or list of fields to include
- `True` to include all other fields
- `None`/`False` to include no other fields
* **include_indexes** (*False*) – whether to recreate any custom indexes on
`field_or_expr` and `other_fields` on the clips view (True)
or a list of specific indexes or index prefixes to recreate.
By default, no custom indexes are recreated
* **tol** (*0*) – the maximum number of false frames that can be overlooked
when generating clips. Only applicable when `field_or_expr`
is a frame-level list field or expression
* **min_len** (*0*) – the minimum allowable length of a clip, in frames.
Only applicable when `field_or_expr` is a frame-level list
field or an expression
* **trajectories** (*False*) – whether to create clips for each unique
object trajectory defined by their `(label, index)`. Only
applicable when `field_or_expr` is a frame-level field
* **Returns:**
a [`fiftyone.core.clips.ClipsView`](#fiftyone.core.clips.ClipsView)
#### to_dict(rel_dir=None, include_private=False, include_frames=False, frame_labels_dir=None, pretty_print=False)
Returns a JSON dictionary representation of the view.
* **Parameters:**
* **rel_dir** (*None*) – a relative directory to remove from the
`filepath` of each sample, if possible. The path is converted
to an absolute path (if necessary) via
[`fiftyone.core.storage.normalize_path()`](fiftyone.core.storage.md#fiftyone.core.storage.normalize_path). The typical use
case for this argument is that your source data lives in a
single directory and you wish to serialize relative, rather
than absolute, paths to the data within that directory
* **include_private** (*False*) – whether to include private fields
* **include_frames** (*False*) – whether to include the frame labels for
video samples
* **frame_labels_dir** (*None*) – a directory in which to write per-sample
JSON files containing the frame labels for video samples. If
omitted, frame labels will be included directly in the returned
JSON dict (which can be quite quite large for video datasets
containing many frames). Only applicable to datasets that
contain videos when `include_frames` is True
* **pretty_print** (*False*) – whether to render frame labels JSON in human
readable format with newlines and indentations. Only applicable
to datasets that contain videos when a `frame_labels_dir` is
provided
* **Returns:**
a JSON dict
#### to_evaluation_patches(eval_key, \*\*kwargs)
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.clips.ClipsView.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
#
view = dataset.to_evaluation_patches("eval")
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`](fiftyone.core.labels.md#fiftyone.core.labels.Polylines), or
[`fiftyone.core.labels.Keypoints`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoints)
* **other_fields** (*None*) –
controls whether fields other than the
ground truth/predicted fields and the default sample fields are
included. Can be any of the following:
- a field or list of fields to include
- `True` to include all other fields
- `None`/`False` to include no other fields
* **include_indexes** (*False*) – whether to recreate any custom indexes on
the ground truth/predicted fields and `other_fields` on the
patches view (True) or a list of specific indexes or index
prefixes to recreate. By default, no custom indexes are
recreated
* **Returns:**
a [`fiftyone.core.patches.EvaluationPatchesView`](fiftyone.core.patches.md#fiftyone.core.patches.EvaluationPatchesView)
#### to_frames(\*\*kwargs)
Creates a view that contains one sample per frame in the 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
#
frames = dataset.to_frames(sample_frames=True)
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)
frames = view.to_frames(max_fps=1)
print(frames)
session.view = frames
```
* **Parameters:**
* **sample_frames** (*False*) – whether to assume that the frame images have
already been sampled at locations stored in the `filepath`
field of each frame (False), or whether to sample the video
frames now according to the specified parameters (True)
* **fps** (*None*) – an optional frame rate at which to sample each video’s
frames
* **max_fps** (*None*) – an optional maximum frame rate at which to sample.
Videos with frame rate exceeding this value are downsampled
* **size** (*None*) – an optional `(width, height)` at which to sample
frames. A dimension can be -1, in which case the aspect ratio
is preserved. Only applicable when `sample_frames=True`
* **min_size** (*None*) – an optional minimum `(width, height)` for each
frame. A dimension can be -1 if no constraint should be
applied. The frames are resized (aspect-preserving) if
necessary to meet this constraint. Only applicable when
`sample_frames=True`
* **max_size** (*None*) – an optional maximum `(width, height)` for each
frame. A dimension can be -1 if no constraint should be
applied. The frames are resized (aspect-preserving) if
necessary to meet this constraint. Only applicable when
`sample_frames=True`
* **sparse** (*False*) – whether to only sample frame images for frame
numbers for which [`fiftyone.core.frame.Frame`](fiftyone.core.frame.md#fiftyone.core.frame.Frame) instances
exist in the input collection. This parameter has no effect
when `sample_frames==False` since frames must always exist in
order to have `filepath` information use
* **output_dir** (*None*) – an optional output directory in which to write
the sampled frames. By default, the frames are written in
folders with the same basename of each video
* **rel_dir** (*None*) – a relative directory to remove from the filepath of
each video, if possible. The path is converted to an absolute
path (if necessary) via
[`fiftyone.core.storage.normalize_path()`](fiftyone.core.storage.md#fiftyone.core.storage.normalize_path). This argument can
be used in conjunction with `output_dir` to cause the sampled
frames to be written in a nested directory structure within
`output_dir` matching the shape of the input video’s folder
structure
* **frames_patt** (*None*) – a pattern specifying the filename/format to use
to write or check or existing sampled frames, e.g.,
`"%%06d.jpg"`. The default value is
`fiftyone.config.default_sequence_idx + fiftyone.config.default_image_ext`
* **force_sample** (*False*) – whether to resample videos whose sampled
frames already exist. Only applicable when
`sample_frames=True`
* **skip_failures** (*True*) – whether to gracefully continue without
raising an error if a video cannot be sampled
* **verbose** (*False*) – whether to log information about the frames that
will be sampled, if any
* **include_indexes** (*False*) – whether to recreate any custom frame
indexes on the frames view (True) or a list of specific indexes
or index prefixes to recreate. By default, no custom indexes
are recreated
* **Returns:**
a [`fiftyone.core.video.FramesView`](fiftyone.core.video.md#fiftyone.core.video.FramesView)
#### to_json(rel_dir=None, include_private=False, include_frames=False, frame_labels_dir=None, pretty_print=False)
Returns a JSON string representation of the collection.
The samples will be written as a list in a top-level `samples` field
of the returned dictionary.
* **Parameters:**
* **rel_dir** (*None*) – a relative directory to remove from the
`filepath` of each sample, if possible. The path is converted
to an absolute path (if necessary) via
[`fiftyone.core.storage.normalize_path()`](fiftyone.core.storage.md#fiftyone.core.storage.normalize_path). The typical use
case for this argument is that your source data lives in a
single directory and you wish to serialize relative, rather
than absolute, paths to the data within that directory
* **include_private** (*False*) – whether to include private fields
* **include_frames** (*False*) – whether to include the frame labels for
video samples
* **frame_labels_dir** (*None*) – a directory in which to write per-sample
JSON files containing the frame labels for video samples. If
omitted, frame labels will be included directly in the returned
JSON dict (which can be quite quite large for video datasets
containing many frames). Only applicable to datasets that
contain videos when `include_frames` is True
* **pretty_print** (*False*) – whether to render the JSON in human readable
format with newlines and indentations
* **Returns:**
a JSON string
#### to_patches(field, \*\*kwargs)
Creates a view that contains one sample per object patch in the
specified field of the collection.
Fields other than `field` and the default sample fields will not be
included in the returned view. A `sample_id` field will be added that
records the sample ID from which each patch was taken.
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
#
view = dataset.to_patches("ground_truth")
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)
* **other_fields** (*None*) –
controls whether fields other than `field`
and the default sample fields are included. Can be any of the
following:
- a field or list of fields to include
- `True` to include all other fields
- `None`/`False` to include no other fields
* **keep_label_lists** (*False*) – whether to store the patches in label
list fields of the same type as the input collection rather
than using their single label variants
* **include_indexes** (*False*) – whether to recreate any custom indexes on
`field` and `other_fields` on the patches view (True) or a
list of specific indexes or index prefixes to recreate. By
default, no custom indexes are recreated
* **Returns:**
a [`fiftyone.core.patches.PatchesView`](fiftyone.core.patches.md#fiftyone.core.patches.PatchesView)
#### to_torch(get_item, , index_field='id', vectorize=False, skip_failures=False, local_process_group=None)
Constructs a [`torch.utils.data.Dataset`](https://docs.pytorch.org/docs/stable/data.html#torch.utils.data.Dataset) that loads data
from this collection via the provided
[`fiftyone.utils.torch.GetItem`](fiftyone.utils.torch.md#fiftyone.utils.torch.GetItem) instance.
* **Parameters:**
* **get_item** – a [`fiftyone.utils.torch.GetItem`](fiftyone.utils.torch.md#fiftyone.utils.torch.GetItem)
* **index_field** ( *"id"*) – the dotted field path that defines the
dataset’s rows. The default `"id"` yields one row per
sample. Use a list-valued path such as `"frames.id"` or
`"ground_truth.detections.id"` to fan out into one row per
frame, detection, etc.
* **vectorize** (*False*) – whether to load and cache the required fields
from the sample collection upfront (True) or lazily load the
values from each sample when items are retrieved (False).
Vectorizing gives faster data loading times, but you must have
enough memory to store the required field values for the entire
sample collection. When `vectorize=True`, all field values
must be serializable; ie `pickle.dumps(field_value)` must not
raise an error
* **skip_failures** (*False*) – whether to skip failures that occur when
calling `get_item`. If True, the exception will be returned
rather than the intended field values
* **local_process_group** (*None*) – the local process group. Only used
during distributed training
* **Returns:**
a [`torch.utils.data.Dataset`](https://docs.pytorch.org/docs/stable/data.html#torch.utils.data.Dataset)
#### to_trajectories(field, \*\*kwargs)
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
#
trajectories = (
dataset
.filter_labels("frames.detections", F("label") == "vehicle")
.to_trajectories("frames.detections")
)
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)
* **other_fields** (*None*) –
controls whether sample fields other than the
default sample fields are included. Can be any of the
following:
- a field or list of fields to include
- `True` to include all other fields
- `None`/`False` to include no other fields
* **include_indexes** (*False*) – whether to recreate any custom indexes on
`other_fields` on the clips view (True) or a list of specific
indexes or index prefixes to recreate. By default, no custom
indexes are recreated
* **tol** (*0*) – the maximum number of false frames that can be overlooked
when generating clips
* **min_len** (*0*) – the minimum allowable length of a clip, in frames
* **Returns:**
a [`fiftyone.core.clips.TrajectoriesView`](#fiftyone.core.clips.TrajectoriesView)
#### untag_labels(tags, label_fields=None)
Removes the tag from all labels in the specified label field(s) of
this collection, if necessary.
* **Parameters:**
* **tags** – a tag or iterable of tags
* **label_fields** (*None*) – an optional name or iterable of names of
[`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) fields. By default, all
label fields are used
#### untag_samples(tags)
Removes the tag(s) from all samples in this collection, if
necessary.
* **Parameters:**
**tags** – a tag or iterable of tags
#### update_run_config(run_key, config)
Updates the run config for the run with the given key.
* **Parameters:**
* **run_key** – a run key
* **config** – a [`fiftyone.core.runs.RunConfig`](fiftyone.core.runs.md#fiftyone.core.runs.RunConfig)
#### update_samples(update_fcn, skip_failures=True, parallelize_method=None, num_workers=None, batch_method=None, batch_size=None, progress=None)
Applies the given function to each sample in the collection and
saves the resulting sample edits.
By default, a multiprocessing pool is used to parallelize the work,
unless this method is called in a daemon process (subprocess), in which
case no workers are used.
This function effectively performs the following map operation with the
outer loop in parallel:
```default
for batch_view in fou.iter_slices(sample_collection, batch_size):
for sample in batch_view.iter_samples(autosave=True):
map_fcn(sample)
```
Example:
```default
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("cifar10", split="train")
view = dataset.select_fields("ground_truth")
def update_fcn(sample):
sample.ground_truth.label = sample.ground_truth.label.upper()
view.update_samples(update_fcn)
print(dataset.count_values("ground_truth.label"))
```
* **Parameters:**
* **update_fcn** – a function to apply to each sample in the collection
* **skip_failures** (*True*) – whether to gracefully continue without
raising an error if the update function raises an exception for
a sample
* **parallelize_method** (*None*) – the parallelization method to use.
Supported values are `{"process", "thread"}`. The default is
`fiftyone.config.default_parallelization_method`
* **num_workers** (*None*) – the number of workers to use. When using
process parallelism, this defaults to
`fiftyone.config.default_process_pool_workers` if the value
is set, else
[`fiftyone.core.utils.recommend_process_pool_workers()`](fiftyone.core.utils.md#fiftyone.core.utils.recommend_process_pool_workers)
workers are used. If this value is <= 1, all work is done in
the main process
* **batch_method** (*None*) – whether to use IDs (`"id"`) or slices
(`"slice"`) to assign samples to workers
* **batch_size** (*None*) – an optional number of samples to distribute to
each worker at a time. By default, samples are evenly
distributed to workers with one batch per worker
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead, or
“workers” to render per-worker progress bars
#### validate_field_type(path, ftype=None, embedded_doc_type=None, subfield=None)
Validates that the collection has a field of the given type.
* **Parameters:**
* **path** – a field name or `embedded.field.name`
* **ftype** (*None*) – an optional field type or iterable of types to
enforce. Must be subclass(es) of
[`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
* **embedded_doc_type** (*None*) – an optional embedded document type or
iterable of types to enforce. Must be subclass(es) of
[`fiftyone.core.odm.BaseEmbeddedDocument`](fiftyone.core.odm.md#fiftyone.core.odm.BaseEmbeddedDocument)
* **subfield** (*None*) – an optional subfield type or iterable of subfield
types to enforce. Must be subclass(es) of
[`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
* **Raises:**
**ValueError** – if the field does not exist or does not have the
expected type
#### validate_fields_exist(fields, include_private=False)
Validates that the collection has field(s) with the given name(s).
If embedded field names are provided, only the root field is checked.
* **Parameters:**
* **fields** – a field name or iterable of field names
* **include_private** (*False*) – whether to include private fields when
checking for existence
* **Raises:**
**ValueError** – if one or more of the fields do not exist
#### values(field_or_expr, expr=None, missing_value=None, unwind=False, \_allow_missing=False, \_big_result=True, \_raw=False, \_field=None, \_enforce_natural_order=True)
Extracts the values of a field from all samples in the collection.
Values aggregations are useful for efficiently extracting a slice of
field or embedded field values across all samples in a collection. See
the examples below for more details.
The dual function of [`values()`](#fiftyone.core.clips.ClipsView.values) is [`set_values()`](#fiftyone.core.clips.ClipsView.set_values), which can be
used to efficiently set a field or embedded field of all samples in a
collection by providing lists of values of same structure returned by
this aggregation.
#### NOTE
Unlike other aggregations, [`values()`](#fiftyone.core.clips.ClipsView.values) does not automatically
unwind list fields, which ensures that the returned values match
the potentially-nested structure of the documents.
You can opt-in to unwinding specific list fields using the `[]`
syntax, or you can pass the optional `unwind=True` parameter to
unwind all supported list fields. See
[Aggregating list fields](../user_guide/using_aggregations.md#aggregations-list-fields) for more information.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = fo.Dataset()
dataset.add_samples(
[
fo.Sample(
filepath="/path/to/image1.png",
numeric_field=1.0,
numeric_list_field=[1, 2, 3],
),
fo.Sample(
filepath="/path/to/image2.png",
numeric_field=4.0,
numeric_list_field=[1, 2],
),
fo.Sample(
filepath="/path/to/image3.png",
numeric_field=None,
numeric_list_field=None,
),
]
)
#
# Get all values of a field
#
values = dataset.values("numeric_field")
print(values) # [1.0, 4.0, None]
#
# Get all values of a list field
#
values = dataset.values("numeric_list_field")
print(values) # [[1, 2, 3], [1, 2], None]
#
# Get all values of transformed field
#
values = dataset.values(2 * (F("numeric_field") + 1))
print(values) # [4.0, 10.0, None]
#
# Get values from a label list field
#
dataset = foz.load_zoo_dataset("quickstart")
# list of `Detections`
detections = dataset.values("ground_truth")
# list of lists of `Detection` instances
detections = dataset.values("ground_truth.detections")
# list of lists of detection labels
labels = dataset.values("ground_truth.detections.label")
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate. This can also
be a list or tuple of such arguments, in which case a tuple of
corresponding aggregation results (each receiving the same
additional keyword arguments, if any) will be returned
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **missing_value** (*None*) – a value to insert for missing or
`None`-valued fields
* **unwind** (*False*) – whether to automatically unwind all recognized list
fields (True) or unwind all list fields except the top-level
sample field (-1)
* **Returns:**
the list of values
#### view()
Returns a copy of this view.
* **Returns:**
a `DatasetView`
#### write_json(json_path, rel_dir=None, include_private=False, include_frames=False, frame_labels_dir=None, pretty_print=False)
Writes the collection to disk in JSON format.
* **Parameters:**
* **json_path** – the path to write the JSON
* **rel_dir** (*None*) – a relative directory to remove from the
`filepath` of each sample, if possible. The path is converted
to an absolute path (if necessary) via
[`fiftyone.core.storage.normalize_path()`](fiftyone.core.storage.md#fiftyone.core.storage.normalize_path). The typical use
case for this argument is that your source data lives in a
single directory and you wish to serialize relative, rather
than absolute, paths to the data within that directory
* **include_private** (*False*) – whether to include private fields
* **include_frames** (*False*) – whether to include the frame labels for
video samples
* **frame_labels_dir** (*None*) – a directory in which to write per-sample
JSON files containing the frame labels for video samples. If
omitted, frame labels will be included directly in the returned
JSON dict (which can be quite quite large for video datasets
containing many frames). Only applicable to datasets that
contain videos when `include_frames` is True
* **pretty_print** (*False*) – whether to render the JSON in human readable
format with newlines and indentations
### *class* fiftyone.core.clips.TrajectoriesView(source_collection, clips_stage, clips_dataset, \_stages=None, \_media_type=None, \_name=None)
Bases: [`ClipsView`](#fiftyone.core.clips.ClipsView)
A [`ClipsView`](#fiftyone.core.clips.ClipsView) of object trajectories from a video
[`fiftyone.core.dataset.Dataset`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset).
Trajectories views contain an ordered collection of clips, each of which
corresponds to a unique object trajectory from the source collection.
Clips retrieved from trajectories views are returned as [`ClipView`](#fiftyone.core.clips.ClipView)
objects.
* **Parameters:**
* **source_collection** – the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) from which this
view was created
* **clips_stage** – the [`fiftyone.core.stages.ToTrajectories`](fiftyone.core.stages.md#fiftyone.core.stages.ToTrajectories) stage
that defines how the clips were created
* **clips_dataset** – the [`fiftyone.core.dataset.Dataset`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset) that serves
the clips in this view
**Attributes:**
| [`name`](#fiftyone.core.clips.TrajectoriesView.name) | The name of the view if it is a saved view; otherwise None. |
|--------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
| [`is_saved`](#fiftyone.core.clips.TrajectoriesView.is_saved) | Whether the view is a saved view or not. |
| [`media_type`](#fiftyone.core.clips.TrajectoriesView.media_type) | The media type of the view. |
| [`app_config`](#fiftyone.core.clips.TrajectoriesView.app_config) | Dataset-specific settings that customize how this collection is visualized in the [FiftyOne App](../user_guide/app.md#fiftyone-app). |
| [`camera_intrinsics`](#fiftyone.core.clips.TrajectoriesView.camera_intrinsics) | The camera intrinsics of the underlying dataset. |
| [`classes`](#fiftyone.core.clips.TrajectoriesView.classes) | The classes of the underlying dataset. |
| [`dataset_name`](#fiftyone.core.clips.TrajectoriesView.dataset_name) | The name of the underlying dataset. |
| [`default_classes`](#fiftyone.core.clips.TrajectoriesView.default_classes) | The default classes of the underlying dataset. |
| [`default_group_slice`](#fiftyone.core.clips.TrajectoriesView.default_group_slice) | The default group slice of the view, or None if the view is not grouped. |
| [`default_mask_targets`](#fiftyone.core.clips.TrajectoriesView.default_mask_targets) | The default mask targets of the underlying dataset. |
| [`default_skeleton`](#fiftyone.core.clips.TrajectoriesView.default_skeleton) | The default keypoint skeleton of the underlying dataset. |
| [`description`](#fiftyone.core.clips.TrajectoriesView.description) | A description of the underlying dataset. |
| [`group_field`](#fiftyone.core.clips.TrajectoriesView.group_field) | The group field of the view, or None if the view is not grouped. |
| [`group_media_types`](#fiftyone.core.clips.TrajectoriesView.group_media_types) | A dict mapping group slices to media types, or None if the view is not grouped. |
| [`group_slice`](#fiftyone.core.clips.TrajectoriesView.group_slice) | The current group slice of the view, or None if the view is not grouped. |
| [`group_slices`](#fiftyone.core.clips.TrajectoriesView.group_slices) | The list of group slices of the view, or None if the view is not grouped. |
| [`has_annotation_runs`](#fiftyone.core.clips.TrajectoriesView.has_annotation_runs) | Whether this collection has any annotation runs. |
| [`has_brain_runs`](#fiftyone.core.clips.TrajectoriesView.has_brain_runs) | Whether this collection has any brain runs. |
| [`has_evaluations`](#fiftyone.core.clips.TrajectoriesView.has_evaluations) | Whether this collection has any evaluation results. |
| [`has_runs`](#fiftyone.core.clips.TrajectoriesView.has_runs) | Whether this collection has any runs. |
| [`info`](#fiftyone.core.clips.TrajectoriesView.info) | The info dict of the underlying dataset. |
| [`mask_targets`](#fiftyone.core.clips.TrajectoriesView.mask_targets) | The mask targets of the underlying dataset. |
| [`skeletons`](#fiftyone.core.clips.TrajectoriesView.skeletons) | The keypoint skeletons of the underlying dataset. |
| [`static_transforms`](#fiftyone.core.clips.TrajectoriesView.static_transforms) | The static transforms of the underlying dataset. |
| [`tags`](#fiftyone.core.clips.TrajectoriesView.tags) | The list of tags of the underlying dataset. |
**Methods:**
| [`add_stage`](#fiftyone.core.clips.TrajectoriesView.add_stage)(stage) | Applies the given [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage) to the collection. |
|-------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`aggregate`](#fiftyone.core.clips.TrajectoriesView.aggregate)(aggregations[, \_mongo]) | Aggregates one or more [`fiftyone.core.aggregations.Aggregation`](fiftyone.core.aggregations.md#fiftyone.core.aggregations.Aggregation) instances. |
| [`annotate`](#fiftyone.core.clips.TrajectoriesView.annotate)(anno_key[, label_schema, ...]) | Exports the samples and optional label field(s) in this collection to the given annotation backend. |
| [`apply_model`](#fiftyone.core.clips.TrajectoriesView.apply_model)(model[, label_field, ...]) | Applies the model to the samples in the collection. |
| [`bounds`](#fiftyone.core.clips.TrajectoriesView.bounds)(field_or_expr[, expr, safe]) | Computes the bounds of a numeric field of the collection. |
| [`clear`](#fiftyone.core.clips.TrajectoriesView.clear)() | Deletes all samples in the view from the underlying dataset. |
| [`clear_frame_field`](#fiftyone.core.clips.TrajectoriesView.clear_frame_field)(field_name) | Clears the values of the frame-level field from all samples in the view. |
| [`clear_frame_fields`](#fiftyone.core.clips.TrajectoriesView.clear_frame_fields)(field_names) | Clears the values of the frame-level fields from all samples in the view. |
| [`clear_frames`](#fiftyone.core.clips.TrajectoriesView.clear_frames)() | Deletes all frame labels from the samples in the view from the underlying dataset. |
| [`clear_sample_field`](#fiftyone.core.clips.TrajectoriesView.clear_sample_field)(field_name) | Clears the values of the field from all samples in the view. |
| [`clear_sample_fields`](#fiftyone.core.clips.TrajectoriesView.clear_sample_fields)(field_names) | Clears the values of the fields from all samples in the view. |
| [`clone`](#fiftyone.core.clips.TrajectoriesView.clone)([name, persistent, include_indexes]) | Creates a new dataset containing a copy of the contents of the view. |
| [`clone_frame_field`](#fiftyone.core.clips.TrajectoriesView.clone_frame_field)(field_name, new_field_name) | Clones the frame-level field of the view into a new field. |
| [`clone_frame_fields`](#fiftyone.core.clips.TrajectoriesView.clone_frame_fields)(field_mapping) | Clones the frame-level fields of the view into new frame-level fields of the dataset. |
| [`clone_sample_field`](#fiftyone.core.clips.TrajectoriesView.clone_sample_field)(field_name, new_field_name) | Clones the given sample field of the view into a new field of the dataset. |
| [`clone_sample_fields`](#fiftyone.core.clips.TrajectoriesView.clone_sample_fields)(field_mapping) | Clones the given sample fields of the view into new fields of the dataset. |
| [`compute_embeddings`](#fiftyone.core.clips.TrajectoriesView.compute_embeddings)(model[, ...]) | Computes embeddings for the samples in the collection using the given model. |
| [`compute_metadata`](#fiftyone.core.clips.TrajectoriesView.compute_metadata)([overwrite, num_workers, ...]) | Populates the `metadata` field of all samples in the collection. |
| [`compute_patch_embeddings`](#fiftyone.core.clips.TrajectoriesView.compute_patch_embeddings)(model, patches_field) | Computes embeddings for the image patches defined by `patches_field` of the samples in the collection using the given model. |
| [`concat`](#fiftyone.core.clips.TrajectoriesView.concat)(samples) | Concatenates the contents of the given `SampleCollection` to this collection. |
| [`count`](#fiftyone.core.clips.TrajectoriesView.count)([field_or_expr, expr, safe]) | Counts the number of field values in the collection. |
| [`count_label_tags`](#fiftyone.core.clips.TrajectoriesView.count_label_tags)([label_fields]) | Counts the occurrences of all label tags in the specified label field(s) of this collection. |
| [`count_sample_tags`](#fiftyone.core.clips.TrajectoriesView.count_sample_tags)() | Counts the occurrences of sample tags in this collection. |
| [`count_values`](#fiftyone.core.clips.TrajectoriesView.count_values)(field_or_expr[, expr, safe]) | Counts the occurrences of field values in the collection. |
| [`create_index`](#fiftyone.core.clips.TrajectoriesView.create_index)(field_or_spec[, unique, force, ...]) | Creates an index on the given field or with the given specification, if necessary. |
| [`delete_annotation_run`](#fiftyone.core.clips.TrajectoriesView.delete_annotation_run)(anno_key) | Deletes the annotation run with the given key from this collection. |
| [`delete_annotation_runs`](#fiftyone.core.clips.TrajectoriesView.delete_annotation_runs)() | Deletes all annotation runs from this collection. |
| [`delete_brain_run`](#fiftyone.core.clips.TrajectoriesView.delete_brain_run)(brain_key) | Deletes the brain method run with the given key from this collection. |
| [`delete_brain_runs`](#fiftyone.core.clips.TrajectoriesView.delete_brain_runs)() | Deletes all brain method runs from this collection. |
| [`delete_evaluation`](#fiftyone.core.clips.TrajectoriesView.delete_evaluation)(eval_key) | Deletes the evaluation results associated with the given evaluation key from this collection. |
| [`delete_evaluations`](#fiftyone.core.clips.TrajectoriesView.delete_evaluations)() | Deletes all evaluation results from this collection. |
| [`delete_run`](#fiftyone.core.clips.TrajectoriesView.delete_run)(run_key) | Deletes the run with the given key from this collection. |
| [`delete_runs`](#fiftyone.core.clips.TrajectoriesView.delete_runs)() | Deletes all runs from this collection. |
| [`distinct`](#fiftyone.core.clips.TrajectoriesView.distinct)(field_or_expr[, expr, safe]) | Computes the distinct values of a field in the collection. |
| [`draw_labels`](#fiftyone.core.clips.TrajectoriesView.draw_labels)(output_dir[, rel_dir, ...]) | Renders annotated versions of the media in the collection with the specified label data overlaid to the given directory. |
| [`drop_index`](#fiftyone.core.clips.TrajectoriesView.drop_index)(field_or_name) | Drops the index for the given field or name, if necessary. |
| [`ensure_frames`](#fiftyone.core.clips.TrajectoriesView.ensure_frames)() | Ensures that the video view contains frame instances for every frame of each sample's source video. |
| [`evaluate_classifications`](#fiftyone.core.clips.TrajectoriesView.evaluate_classifications)(pred_field[, ...]) | Evaluates the classification predictions in this collection with respect to the specified ground truth labels. |
| [`evaluate_detections`](#fiftyone.core.clips.TrajectoriesView.evaluate_detections)(pred_field[, gt_field, ...]) | Evaluates the specified predicted detections in this collection with respect to the specified ground truth detections. |
| [`evaluate_regressions`](#fiftyone.core.clips.TrajectoriesView.evaluate_regressions)(pred_field[, gt_field, ...]) | Evaluates the regression predictions in this collection with respect to the specified ground truth values. |
| [`evaluate_segmentations`](#fiftyone.core.clips.TrajectoriesView.evaluate_segmentations)(pred_field[, ...]) | Evaluates the specified semantic segmentation masks in this collection with respect to the specified ground truth masks. |
| [`exclude`](#fiftyone.core.clips.TrajectoriesView.exclude)(sample_ids) | Excludes the samples with the given IDs from the collection. |
| [`exclude_by`](#fiftyone.core.clips.TrajectoriesView.exclude_by)(field, values) | Excludes the samples with the given field values from the collection. |
| [`exclude_fields`](#fiftyone.core.clips.TrajectoriesView.exclude_fields)([field_names, meta_filter, ...]) | Excludes the fields with the given names from the samples in the collection. |
| [`exclude_frames`](#fiftyone.core.clips.TrajectoriesView.exclude_frames)(frame_ids[, omit_empty]) | Excludes the frames with the given IDs from the video collection. |
| [`exclude_group_slices`](#fiftyone.core.clips.TrajectoriesView.exclude_group_slices)([slices, media_type]) | Excludes the specified group slice(s) from the grouped collection. |
| [`exclude_groups`](#fiftyone.core.clips.TrajectoriesView.exclude_groups)(group_ids) | Excludes the groups with the given IDs from the grouped collection. |
| [`exclude_labels`](#fiftyone.core.clips.TrajectoriesView.exclude_labels)([labels, ids, instance_ids, ...]) | Excludes the specified labels from the collection. |
| [`exists`](#fiftyone.core.clips.TrajectoriesView.exists)(field[, bool]) | Returns a view containing the samples in the collection that have (or do not have) a non-`None` value for the given field or embedded field. |
| [`export`](#fiftyone.core.clips.TrajectoriesView.export)([export_dir, dataset_type, ...]) | Exports the samples in the collection to disk. |
| [`filter_field`](#fiftyone.core.clips.TrajectoriesView.filter_field)(field, filter[, only_matches]) | Filters the values of a field or embedded field of each sample in the collection. |
| [`filter_keypoints`](#fiftyone.core.clips.TrajectoriesView.filter_keypoints)(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. |
| [`filter_labels`](#fiftyone.core.clips.TrajectoriesView.filter_labels)(field, filter[, only_matches, ...]) | Filters the [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) field of each sample in the collection. |
| [`first`](#fiftyone.core.clips.TrajectoriesView.first)() | Returns the first sample in the collection. |
| [`flatten`](#fiftyone.core.clips.TrajectoriesView.flatten)([stages]) | Returns a flattened view that contains all samples in the dynamic grouped collection. |
| [`generate_label_schemas`](#fiftyone.core.clips.TrajectoriesView.generate_label_schemas)([fields, scan_samples]) | Generates label schemas for the [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection). |
| [`geo_near`](#fiftyone.core.clips.TrajectoriesView.geo_near)(point[, location_field, ...]) | Sorts the samples in the collection by their proximity to a specified geolocation. |
| [`geo_within`](#fiftyone.core.clips.TrajectoriesView.geo_within)(boundary[, location_field, ...]) | Filters the samples in this collection to only include samples whose geolocation is within a specified boundary. |
| [`get_annotation_info`](#fiftyone.core.clips.TrajectoriesView.get_annotation_info)(anno_key) | Returns information about the annotation run with the given key on this collection. |
| [`get_brain_info`](#fiftyone.core.clips.TrajectoriesView.get_brain_info)(brain_key) | Returns information about the brain method run with the given key on this collection. |
| [`get_classes`](#fiftyone.core.clips.TrajectoriesView.get_classes)(field) | Gets the classes list for the given field, or None if no classes are available. |
| [`get_dynamic_field_schema`](#fiftyone.core.clips.TrajectoriesView.get_dynamic_field_schema)([fields, recursive]) | Returns a schema dictionary describing the dynamic fields of the samples in the collection. |
| [`get_dynamic_frame_field_schema`](#fiftyone.core.clips.TrajectoriesView.get_dynamic_frame_field_schema)([fields, ...]) | Returns a schema dictionary describing the dynamic fields of the frames in the collection. |
| [`get_dynamic_group`](#fiftyone.core.clips.TrajectoriesView.get_dynamic_group)(group_value) | Returns a view containing the samples from a dynamic grouped view with the given group value. |
| [`get_evaluation_info`](#fiftyone.core.clips.TrajectoriesView.get_evaluation_info)(eval_key) | Returns information about the evaluation with the given key on this collection. |
| [`get_field`](#fiftyone.core.clips.TrajectoriesView.get_field)(path[, ftype, embedded_doc_type, ...]) | Returns the field instance of the provided path, or `None` if one does not exist. |
| [`get_field_schema`](#fiftyone.core.clips.TrajectoriesView.get_field_schema)([ftype, embedded_doc_type, ...]) | Returns a schema dictionary describing the fields of the samples in the view. |
| [`get_frame_field_schema`](#fiftyone.core.clips.TrajectoriesView.get_frame_field_schema)([ftype, ...]) | Returns a schema dictionary describing the fields of the frames of the samples in the view. |
| [`get_group`](#fiftyone.core.clips.TrajectoriesView.get_group)(group_id[, group_slices]) | Returns a dict containing the samples for the given group ID. |
| [`get_index_information`](#fiftyone.core.clips.TrajectoriesView.get_index_information)([include_stats, ...]) | Returns a dictionary of information about the indexes on this collection. |
| [`get_mask_targets`](#fiftyone.core.clips.TrajectoriesView.get_mask_targets)(field) | Gets the mask targets for the given field, or None if no mask targets are available. |
| [`get_run_info`](#fiftyone.core.clips.TrajectoriesView.get_run_info)(run_key) | Returns information about the run with the given key on this collection. |
| [`get_skeleton`](#fiftyone.core.clips.TrajectoriesView.get_skeleton)(field) | Gets the keypoint skeleton for the given field, or None if no skeleton is available. |
| [`group_by`](#fiftyone.core.clips.TrajectoriesView.group_by)(field_or_expr[, order_by, reverse, ...]) | Creates a view that groups the samples in the collection by a specified field or expression. |
| [`has_annotation_run`](#fiftyone.core.clips.TrajectoriesView.has_annotation_run)(anno_key) | Whether this collection has an annotation run with the given key. |
| [`has_brain_run`](#fiftyone.core.clips.TrajectoriesView.has_brain_run)(brain_key) | Whether this collection has a brain method run with the given key. |
| [`has_classes`](#fiftyone.core.clips.TrajectoriesView.has_classes)(field) | Determines whether this collection has a classes list for the given field. |
| [`has_evaluation`](#fiftyone.core.clips.TrajectoriesView.has_evaluation)(eval_key) | Whether this collection has an evaluation with the given key. |
| [`has_field`](#fiftyone.core.clips.TrajectoriesView.has_field)(path) | Determines whether the collection has a field with the given name. |
| [`has_frame_field`](#fiftyone.core.clips.TrajectoriesView.has_frame_field)(path) | Determines whether the collection has a frame-level field with the given name. |
| [`has_mask_targets`](#fiftyone.core.clips.TrajectoriesView.has_mask_targets)(field) | Determines whether this collection has mask targets for the given field. |
| [`has_run`](#fiftyone.core.clips.TrajectoriesView.has_run)(run_key) | Whether this collection has a run with the given key. |
| [`has_sample_field`](#fiftyone.core.clips.TrajectoriesView.has_sample_field)(path) | Determines whether the collection has a sample field with the given name. |
| [`has_skeleton`](#fiftyone.core.clips.TrajectoriesView.has_skeleton)(field) | Determines whether this collection has a keypoint skeleton for the given field. |
| [`head`](#fiftyone.core.clips.TrajectoriesView.head)([num_samples]) | Returns a list of the first few samples in the collection. |
| [`histogram_values`](#fiftyone.core.clips.TrajectoriesView.histogram_values)(field_or_expr[, expr, ...]) | Computes a histogram of the field values in the collection. |
| [`init_run`](#fiftyone.core.clips.TrajectoriesView.init_run)(\*\*kwargs) | Initializes a config instance for a new run. |
| [`init_run_results`](#fiftyone.core.clips.TrajectoriesView.init_run_results)(run_key, \*\*kwargs) | Initializes a results instance for the run with the given key. |
| [`iter_dynamic_groups`](#fiftyone.core.clips.TrajectoriesView.iter_dynamic_groups)([progress]) | Returns an iterator over the dynamic groups in the view. |
| [`iter_groups`](#fiftyone.core.clips.TrajectoriesView.iter_groups)([group_slices, progress, ...]) | Returns an iterator over the groups in the view. |
| [`iter_samples`](#fiftyone.core.clips.TrajectoriesView.iter_samples)([progress, autosave, ...]) | Returns an iterator over the samples in the view. |
| [`keep`](#fiftyone.core.clips.TrajectoriesView.keep)() | Deletes all clips that are **not** in this view from the underlying dataset. |
| [`keep_fields`](#fiftyone.core.clips.TrajectoriesView.keep_fields)() | Deletes any frame fields that have been excluded in this view from the frames of the underlying dataset. |
| [`keep_frames`](#fiftyone.core.clips.TrajectoriesView.keep_frames)() | For each sample in the view, deletes all frames labels that are **not** in the view from the underlying dataset. |
| [`last`](#fiftyone.core.clips.TrajectoriesView.last)() | Returns the last sample in the collection. |
| [`limit`](#fiftyone.core.clips.TrajectoriesView.limit)(limit) | Returns a view with at most the given number of samples. |
| [`limit_labels`](#fiftyone.core.clips.TrajectoriesView.limit_labels)(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 the collection. |
| [`list_aggregations`](#fiftyone.core.clips.TrajectoriesView.list_aggregations)() | Returns a list of all available methods on this collection that apply [`fiftyone.core.aggregations.Aggregation`](fiftyone.core.aggregations.md#fiftyone.core.aggregations.Aggregation) operations to this collection. |
| [`list_annotation_runs`](#fiftyone.core.clips.TrajectoriesView.list_annotation_runs)([type, method]) | Returns a list of annotation keys on this collection. |
| [`list_brain_runs`](#fiftyone.core.clips.TrajectoriesView.list_brain_runs)([type, method]) | Returns a list of brain keys on this collection. |
| [`list_evaluations`](#fiftyone.core.clips.TrajectoriesView.list_evaluations)([type, method]) | Returns a list of evaluation keys on this collection. |
| [`list_indexes`](#fiftyone.core.clips.TrajectoriesView.list_indexes)() | Returns the list of index names on this collection. |
| [`list_runs`](#fiftyone.core.clips.TrajectoriesView.list_runs)(\*\*kwargs) | Returns a list of run keys on this collection. |
| [`list_schema`](#fiftyone.core.clips.TrajectoriesView.list_schema)(field_or_expr[, expr]) | Extracts the value type(s) in a specified list field across all samples in the collection. |
| [`list_view_stages`](#fiftyone.core.clips.TrajectoriesView.list_view_stages)() | Returns a list of all available methods on this collection that apply [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage) operations to this collection. |
| [`load_annotation_results`](#fiftyone.core.clips.TrajectoriesView.load_annotation_results)(anno_key[, cache]) | Loads the results for the annotation run with the given key on this collection. |
| [`load_annotation_view`](#fiftyone.core.clips.TrajectoriesView.load_annotation_view)(anno_key[, select_fields]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) on which the specified annotation run was performed on this collection. |
| [`load_annotations`](#fiftyone.core.clips.TrajectoriesView.load_annotations)(anno_key[, dest_field, ...]) | Downloads the labels from the given annotation run from the annotation backend and merges them into this collection. |
| [`load_brain_results`](#fiftyone.core.clips.TrajectoriesView.load_brain_results)(brain_key[, cache, load_view]) | Loads the results for the brain method run with the given key on this collection. |
| [`load_brain_view`](#fiftyone.core.clips.TrajectoriesView.load_brain_view)(brain_key[, select_fields]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) on which the specified brain method run was performed on this collection. |
| [`load_evaluation_results`](#fiftyone.core.clips.TrajectoriesView.load_evaluation_results)(eval_key[, cache]) | Loads the results for the evaluation with the given key on this collection. |
| [`load_evaluation_view`](#fiftyone.core.clips.TrajectoriesView.load_evaluation_view)(eval_key[, select_fields]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) on which the specified evaluation was performed on this collection. |
| [`load_run_results`](#fiftyone.core.clips.TrajectoriesView.load_run_results)(run_key[, cache, load_view]) | Loads the results for the run with the given key on this collection. |
| [`load_run_view`](#fiftyone.core.clips.TrajectoriesView.load_run_view)(run_key[, select_fields]) | Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) on which the specified run was performed on this collection. |
| [`make_unique_field_name`](#fiftyone.core.clips.TrajectoriesView.make_unique_field_name)([root]) | Makes a unique field name with the given root name for the collection. |
| [`map_labels`](#fiftyone.core.clips.TrajectoriesView.map_labels)(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 the collection. |
| [`map_samples`](#fiftyone.core.clips.TrajectoriesView.map_samples)(map_fcn[, save, skip_failures, ...]) | Applies the given function to each sample in the collection and returns the results as a generator. |
| [`map_values`](#fiftyone.core.clips.TrajectoriesView.map_values)(field, map) | Maps the values in the given field to new values for each sample in the collection. |
| [`match`](#fiftyone.core.clips.TrajectoriesView.match)(filter) | Filters the samples in the collection by the given filter. |
| [`match_frames`](#fiftyone.core.clips.TrajectoriesView.match_frames)(filter[, omit_empty]) | Filters the frames in the video collection by the given filter. |
| [`match_labels`](#fiftyone.core.clips.TrajectoriesView.match_labels)([labels, ids, instance_ids, ...]) | Selects the samples from the collection that contain (or do not contain) at least one label that matches the specified criteria. |
| [`match_tags`](#fiftyone.core.clips.TrajectoriesView.match_tags)(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). |
| [`max`](#fiftyone.core.clips.TrajectoriesView.max)(field_or_expr[, expr, safe]) | Computes the maximum of a numeric field of the collection. |
| [`mean`](#fiftyone.core.clips.TrajectoriesView.mean)(field_or_expr[, expr, safe]) | Computes the arithmetic mean of the field values of the collection. |
| [`merge_labels`](#fiftyone.core.clips.TrajectoriesView.merge_labels)(in_field, out_field) | Merges the labels from the given input field into the given output field of the collection. |
| [`min`](#fiftyone.core.clips.TrajectoriesView.min)(field_or_expr[, expr, safe]) | Computes the minimum of a numeric field of the collection. |
| [`mongo`](#fiftyone.core.clips.TrajectoriesView.mongo)(pipeline[, \_needs_frames, \_group_slices]) | Adds a view stage defined by a raw MongoDB aggregation pipeline. |
| [`one`](#fiftyone.core.clips.TrajectoriesView.one)(expr[, exact]) | Returns a single sample in this collection matching the expression. |
| [`quantiles`](#fiftyone.core.clips.TrajectoriesView.quantiles)(field_or_expr, quantiles[, expr, safe]) | Computes the quantile(s) of the field values of a collection. |
| [`register_run`](#fiftyone.core.clips.TrajectoriesView.register_run)(run_key, config[, results, ...]) | Registers a run under the given key on this collection. |
| [`reload`](#fiftyone.core.clips.TrajectoriesView.reload)() | Reloads the view. |
| [`rename_annotation_run`](#fiftyone.core.clips.TrajectoriesView.rename_annotation_run)(anno_key, new_anno_key) | Replaces the key for the given annotation run with a new key. |
| [`rename_brain_run`](#fiftyone.core.clips.TrajectoriesView.rename_brain_run)(brain_key, new_brain_key) | Replaces the key for the given brain run with a new key. |
| [`rename_evaluation`](#fiftyone.core.clips.TrajectoriesView.rename_evaluation)(eval_key, new_eval_key) | Replaces the key for the given evaluation with a new key. |
| [`rename_run`](#fiftyone.core.clips.TrajectoriesView.rename_run)(run_key, new_run_key) | Replaces the key for the given run with a new key. |
| [`save`](#fiftyone.core.clips.TrajectoriesView.save)([fields]) | Saves the clips in this view to the underlying dataset. |
| [`save_context`](#fiftyone.core.clips.TrajectoriesView.save_context)([batch_size, batching_strategy]) | Returns a context that can be used to save samples from this collection according to a configurable batching strategy. |
| [`save_run_results`](#fiftyone.core.clips.TrajectoriesView.save_run_results)(run_key, results[, ...]) | Saves run results for the run with the given key. |
| [`schema`](#fiftyone.core.clips.TrajectoriesView.schema)(field_or_expr[, expr, dynamic_only, ...]) | Extracts the names and types of the attributes of a specified embedded document field across all samples in the collection. |
| [`select`](#fiftyone.core.clips.TrajectoriesView.select)(sample_ids[, ordered]) | Selects the samples with the given IDs from the collection. |
| [`select_by`](#fiftyone.core.clips.TrajectoriesView.select_by)(field, values[, ordered]) | Selects the samples with the given field values from the collection. |
| [`select_fields`](#fiftyone.core.clips.TrajectoriesView.select_fields)([field_names, meta_filter, ...]) | Selects only the fields with the given names from the samples in the collection. |
| [`select_frames`](#fiftyone.core.clips.TrajectoriesView.select_frames)(frame_ids[, omit_empty]) | Selects the frames with the given IDs from the video collection. |
| [`select_group_slices`](#fiftyone.core.clips.TrajectoriesView.select_group_slices)([slices, media_type, ...]) | Selects the specified group slice(s) from the grouped collection. |
| [`select_groups`](#fiftyone.core.clips.TrajectoriesView.select_groups)(group_ids[, ordered]) | Selects the groups with the given IDs from the grouped collection. |
| [`select_labels`](#fiftyone.core.clips.TrajectoriesView.select_labels)([labels, ids, instance_ids, ...]) | Selects only the specified labels from the collection. |
| [`set_field`](#fiftyone.core.clips.TrajectoriesView.set_field)(field, expr[, \_allow_missing]) | Sets a field or embedded field on each sample in a collection by evaluating the given expression. |
| [`set_label_values`](#fiftyone.core.clips.TrajectoriesView.set_label_values)(field_name, \*args, \*\*kwargs) | Sets the fields of the specified labels in the collection to the given values. |
| [`set_values`](#fiftyone.core.clips.TrajectoriesView.set_values)(field_name, \*args, \*\*kwargs) | Sets the field or embedded field on each sample or frame in the collection to the given values. |
| [`shuffle`](#fiftyone.core.clips.TrajectoriesView.shuffle)([seed]) | Randomly shuffles the samples in the collection. |
| [`skip`](#fiftyone.core.clips.TrajectoriesView.skip)(skip) | Omits the given number of samples from the head of the collection. |
| [`sort_by`](#fiftyone.core.clips.TrajectoriesView.sort_by)(field_or_expr[, reverse, create_index]) | Sorts the samples in the collection by the given field(s) or expression(s). |
| [`sort_by_similarity`](#fiftyone.core.clips.TrajectoriesView.sort_by_similarity)(query[, k, reverse, ...]) | Sorts the collection by similarity to a specified query. |
| [`split_labels`](#fiftyone.core.clips.TrajectoriesView.split_labels)(in_field, out_field[, filter]) | Splits the labels from the given input field into the given output field of the collection. |
| [`stats`](#fiftyone.core.clips.TrajectoriesView.stats)([include_media, include_indexes, ...]) | Returns stats about the collection on disk. |
| [`std`](#fiftyone.core.clips.TrajectoriesView.std)(field_or_expr[, expr, safe, sample]) | Computes the standard deviation of the field values of the collection. |
| [`sum`](#fiftyone.core.clips.TrajectoriesView.sum)(field_or_expr[, expr, safe]) | Computes the sum of the field values of the collection. |
| [`summary`](#fiftyone.core.clips.TrajectoriesView.summary)() | Returns a string summary of the view. |
| [`sync_last_modified_at`](#fiftyone.core.clips.TrajectoriesView.sync_last_modified_at)([include_frames]) | Syncs the `last_modified_at` property(s) of the dataset. |
| [`tag_labels`](#fiftyone.core.clips.TrajectoriesView.tag_labels)(tags[, label_fields]) | Adds the tag(s) to all labels in the specified label field(s) of this collection, if necessary. |
| [`tag_samples`](#fiftyone.core.clips.TrajectoriesView.tag_samples)(tags) | Adds the tag(s) to all samples in this collection, if necessary. |
| [`tail`](#fiftyone.core.clips.TrajectoriesView.tail)([num_samples]) | Returns a list of the last few samples in the collection. |
| [`take`](#fiftyone.core.clips.TrajectoriesView.take)(size[, seed]) | Randomly samples the given number of samples from the collection. |
| [`to_clips`](#fiftyone.core.clips.TrajectoriesView.to_clips)(field_or_expr, \*\*kwargs) | Creates a view that contains one sample per clip defined by the given field or expression in the video collection. |
| [`to_dict`](#fiftyone.core.clips.TrajectoriesView.to_dict)([rel_dir, include_private, ...]) | Returns a JSON dictionary representation of the view. |
| [`to_evaluation_patches`](#fiftyone.core.clips.TrajectoriesView.to_evaluation_patches)(eval_key, \*\*kwargs) | 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. |
| [`to_frames`](#fiftyone.core.clips.TrajectoriesView.to_frames)(\*\*kwargs) | Creates a view that contains one sample per frame in the video collection. |
| [`to_json`](#fiftyone.core.clips.TrajectoriesView.to_json)([rel_dir, include_private, ...]) | Returns a JSON string representation of the collection. |
| [`to_patches`](#fiftyone.core.clips.TrajectoriesView.to_patches)(field, \*\*kwargs) | Creates a view that contains one sample per object patch in the specified field of the collection. |
| [`to_torch`](#fiftyone.core.clips.TrajectoriesView.to_torch)(get_item, \*[, index_field, ...]) | Constructs a [`torch.utils.data.Dataset`](https://docs.pytorch.org/docs/stable/data.html#torch.utils.data.Dataset) that loads data from this collection via the provided [`fiftyone.utils.torch.GetItem`](fiftyone.utils.torch.md#fiftyone.utils.torch.GetItem) instance. |
| [`to_trajectories`](#fiftyone.core.clips.TrajectoriesView.to_trajectories)(field, \*\*kwargs) | 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. |
| [`untag_labels`](#fiftyone.core.clips.TrajectoriesView.untag_labels)(tags[, label_fields]) | Removes the tag from all labels in the specified label field(s) of this collection, if necessary. |
| [`untag_samples`](#fiftyone.core.clips.TrajectoriesView.untag_samples)(tags) | Removes the tag(s) from all samples in this collection, if necessary. |
| [`update_run_config`](#fiftyone.core.clips.TrajectoriesView.update_run_config)(run_key, config) | Updates the run config for the run with the given key. |
| [`update_samples`](#fiftyone.core.clips.TrajectoriesView.update_samples)(update_fcn[, skip_failures, ...]) | Applies the given function to each sample in the collection and saves the resulting sample edits. |
| [`validate_field_type`](#fiftyone.core.clips.TrajectoriesView.validate_field_type)(path[, ftype, ...]) | Validates that the collection has a field of the given type. |
| [`validate_fields_exist`](#fiftyone.core.clips.TrajectoriesView.validate_fields_exist)(fields[, include_private]) | Validates that the collection has field(s) with the given name(s). |
| [`values`](#fiftyone.core.clips.TrajectoriesView.values)(field_or_expr[, expr, missing_value, ...]) | Extracts the values of a field from all samples in the collection. |
| [`view`](#fiftyone.core.clips.TrajectoriesView.view)() | Returns a copy of this view. |
| [`write_json`](#fiftyone.core.clips.TrajectoriesView.write_json)(json_path[, rel_dir, ...]) | Writes the collection to disk in JSON format. |
#### *property* name
The name of the view if it is a saved view; otherwise None.
#### *property* is_saved
Whether the view is a saved view or not.
#### *property* media_type
The media type of the view.
#### add_stage(stage)
Applies the given [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage) to the
collection.
* **Parameters:**
**stage** – a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage)
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### aggregate(aggregations, \_mongo=False)
Aggregates one or more
[`fiftyone.core.aggregations.Aggregation`](fiftyone.core.aggregations.md#fiftyone.core.aggregations.Aggregation) instances.
Note that it is best practice to group aggregations into a single call
to [`aggregate()`](#fiftyone.core.clips.TrajectoriesView.aggregate), as this will be more efficient than performing
multiple aggregations in series.
* **Parameters:**
**aggregations** – an [`fiftyone.core.aggregations.Aggregation`](fiftyone.core.aggregations.md#fiftyone.core.aggregations.Aggregation) or
iterable of [`fiftyone.core.aggregations.Aggregation`](fiftyone.core.aggregations.md#fiftyone.core.aggregations.Aggregation)
instances
* **Returns:**
Aggregation result(s) corresponding to the input aggregation(s).
Returns a single result for a single aggregation, a list of results
for multiple aggregations, or a generator for lazy aggregations
#### annotate(anno_key, label_schema=None, label_field=None, label_type=None, classes=None, attributes=True, mask_targets=None, allow_additions=True, allow_deletions=True, allow_label_edits=True, allow_index_edits=True, allow_spatial_edits=True, media_field='filepath', backend=None, launch_editor=False, \*\*kwargs)
Exports the samples and optional label field(s) in this collection
to the given annotation backend.
The `backend` parameter controls which annotation backend to use.
Depending on the backend you use, you may want/need to provide extra
keyword arguments to this function for the constructor of the backend’s
[`fiftyone.utils.annotations.AnnotationBackendConfig`](fiftyone.utils.annotations.md#fiftyone.utils.annotations.AnnotationBackendConfig) class.
The natively provided backends and their associated config classes are:
- `"cvat"`: [`fiftyone.utils.cvat.CVATBackendConfig`](fiftyone.utils.cvat.md#fiftyone.utils.cvat.CVATBackendConfig)
- `"labelstudio"`: [`fiftyone.utils.labelstudio.LabelStudioBackendConfig`](fiftyone.utils.labelstudio.md#fiftyone.utils.labelstudio.LabelStudioBackendConfig)
- `"labelbox"`: [`fiftyone.utils.labelbox.LabelboxBackendConfig`](fiftyone.utils.labelbox.md#fiftyone.utils.labelbox.LabelboxBackendConfig)
See [this page](../integrations/annotation.md#requesting-annotations) for more information
about using this method, including how to define label schemas and how
to configure login credentials for your annotation provider.
* **Parameters:**
* **anno_key** – a string key to use to refer to this annotation run
* **label_schema** (*None*) – a dictionary defining the label schema to use.
If this argument is provided, it takes precedence over the
other schema-related arguments
* **label_field** (*None*) – a string indicating a new or existing label
field to annotate
* **label_type** (*None*) –
a string indicating the type of labels to
annotate. The possible values are:
- `"classification"`: a single classification stored in
[`fiftyone.core.labels.Classification`](fiftyone.core.labels.md#fiftyone.core.labels.Classification) fields
- `"classifications"`: multilabel classifications stored in
[`fiftyone.core.labels.Classifications`](fiftyone.core.labels.md#fiftyone.core.labels.Classifications) fields
- `"detections"`: object detections stored in
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) fields
- `"instances"`: instance segmentations stored in
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) fields with their
[`mask`](fiftyone.core.labels.md#fiftyone.core.labels.Detection.mask)
attributes populated
- `"polylines"`: polylines stored in
[`fiftyone.core.labels.Polylines`](fiftyone.core.labels.md#fiftyone.core.labels.Polylines) fields with their
[`filled`](fiftyone.core.labels.md#fiftyone.core.labels.Polyline.filled)
attributes set to `False`
- `"polygons"`: polygons stored in
[`fiftyone.core.labels.Polylines`](fiftyone.core.labels.md#fiftyone.core.labels.Polylines) fields with their
[`filled`](fiftyone.core.labels.md#fiftyone.core.labels.Polyline.filled)
attributes set to `True`
- `"keypoints"`: keypoints stored in
[`fiftyone.core.labels.Keypoints`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoints) fields
- `"segmentation"`: semantic segmentations stored in
[`fiftyone.core.labels.Segmentation`](fiftyone.core.labels.md#fiftyone.core.labels.Segmentation) fields
- `"scalar"`: scalar labels stored in
[`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField),
[`fiftyone.core.fields.FloatField`](fiftyone.core.fields.md#fiftyone.core.fields.FloatField),
[`fiftyone.core.fields.StringField`](fiftyone.core.fields.md#fiftyone.core.fields.StringField), or
[`fiftyone.core.fields.BooleanField`](fiftyone.core.fields.md#fiftyone.core.fields.BooleanField) fields
All new label fields must have their type specified via this
argument or in `label_schema`. Note that annotation backends
may not support all label types
* **classes** (*None*) – a list of strings indicating the class options for
`label_field` or all fields in `label_schema` without
classes specified. All new label fields must have a class list
provided via one of the supported methods. For existing label
fields, if classes are not provided by this argument nor
`label_schema`, they are retrieved from [`get_classes()`](#fiftyone.core.clips.TrajectoriesView.get_classes)
if possible, or else the observed labels on your dataset are
used
* **attributes** (*True*) –
specifies the label attributes of each label
field to include (other than their `label`, which is always
included) in the annotation export. Can be any of the
following:
- `True`: export all label attributes
- `False`: don’t export any custom label attributes
- a list of label attributes to export
- a dict mapping attribute names to dicts specifying the
`type`, `values`, and `default` for each attribute
If a `label_schema` is also provided, this parameter
determines which attributes are included for all fields that do
not explicitly define their per-field attributes (in addition
to any per-class attributes)
* **mask_targets** (*None*) – a dict mapping pixel values (2D masks) or RGB
hex strings (3D masks) to semantic label strings. Only
applicable when annotating semantic segmentations. All new
label fields must have mask targets provided via one of the
supported methods. For existing label fields, if mask targets
are not provided by this argument nor `label_schema`, any
applicable mask targets stored on your dataset will be used, if
available
* **allow_additions** (*True*) – whether to allow new labels to be added.
Only applicable when editing existing label fields
* **allow_deletions** (*True*) – whether to allow labels to be deleted. Only
applicable when editing existing label fields
* **allow_label_edits** (*True*) – whether to allow the `label` attribute
of existing labels to be modified. Only applicable when editing
existing fields with `label` attributes
* **allow_index_edits** (*True*) – whether to allow the `index` attribute
of existing video tracks to be modified. Only applicable when
editing existing frame fields with `index` attributes
* **allow_spatial_edits** (*True*) – whether to allow edits to the spatial
properties (bounding boxes, vertices, keypoints, masks, etc) of
labels. Only applicable when editing existing spatial label
fields
* **media_field** ( *"filepath"*) – the field containing the paths to the
media files to upload
* **backend** (*None*) – the annotation backend to use. The supported values
are `fiftyone.annotation_config.backends.keys()` and the
default is `fiftyone.annotation_config.default_backend`
* **launch_editor** (*False*) – whether to launch the annotation backend’s
editor after uploading the samples
* **\*\*kwargs** – keyword arguments for the
[`fiftyone.utils.annotations.AnnotationBackendConfig`](fiftyone.utils.annotations.md#fiftyone.utils.annotations.AnnotationBackendConfig)
* **Returns:**
an `fiftyone.utils.annotations.AnnnotationResults`
#### *property* app_config
Dataset-specific settings that customize how this collection is
visualized in the [FiftyOne App](../user_guide/app.md#fiftyone-app).
#### apply_model(model, label_field='predictions', confidence_thresh=None, classes=None, store_logits=False, batch_size=None, num_workers=None, skip_failures=True, output_dir=None, rel_dir=None, progress=None, \*\*kwargs)
Applies the model to the samples in the collection.
This method supports all of the following cases:
- Applying an image model to an image collection
- Applying an image model to the frames of a video collection
- Applying a video model to a video collection
* **Parameters:**
* **model** – a [`fiftyone.core.models.Model`](fiftyone.core.models.md#fiftyone.core.models.Model), Hugging Face
transformers model, Ultralytics model, SuperGradients model, or
Lightning Flash model
* **label_field** ( *"predictions"*) – the name of the field in which to
store the model predictions. When performing inference on video
frames, the “frames.” prefix is optional
* **confidence_thresh** (*None*) – an optional confidence threshold to apply
to any applicable labels generated by the model
* **classes** (*None*) – an optional iterable of classes to which to
restrict any applicable labels generated by the model
* **store_logits** (*False*) – whether to store logits for the model
predictions. This is only supported when the provided `model`
has logits, `model.has_logits == True`
* **batch_size** (*None*) – an optional batch size to use, if the model
supports batching
* **num_workers** (*None*) – the number of workers for the
[`torch.utils.data.DataLoader`](https://docs.pytorch.org/docs/stable/data.html#torch.utils.data.DataLoader) to use. Only
applicable for Torch-based models
* **skip_failures** (*True*) – whether to gracefully continue without
raising an error if predictions cannot be generated for a
sample. Only applicable to [`fiftyone.core.models.Model`](fiftyone.core.models.md#fiftyone.core.models.Model)
instances
* **output_dir** (*None*) – an optional output directory in which to write
segmentation images. Only applicable if the model generates
segmentations. If none is provided, the segmentations are
stored in the database
* **rel_dir** (*None*) – an optional relative directory to strip from each
input filepath to generate a unique identifier that is joined
with `output_dir` to generate an output path for each
segmentation image. This argument allows for populating nested
subdirectories in `output_dir` that match the shape of the
input paths. The path is converted to an absolute path (if
necessary) via [`fiftyone.core.storage.normalize_path()`](fiftyone.core.storage.md#fiftyone.core.storage.normalize_path)
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **\*\*kwargs** – optional model-specific keyword arguments passed through
to the underlying inference implementation
#### bounds(field_or_expr, expr=None, safe=False)
Computes the bounds of a numeric field of the collection.
`None`-valued fields are ignored.
This aggregation is typically applied to *numeric* or *date* field
types (or lists of such types):
- [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField)
- [`fiftyone.core.fields.FloatField`](fiftyone.core.fields.md#fiftyone.core.fields.FloatField)
- [`fiftyone.core.fields.DateField`](fiftyone.core.fields.md#fiftyone.core.fields.DateField)
- [`fiftyone.core.fields.DateTimeField`](fiftyone.core.fields.md#fiftyone.core.fields.DateTimeField)
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",
numeric_field=1.0,
numeric_list_field=[1, 2, 3],
),
fo.Sample(
filepath="/path/to/image2.png",
numeric_field=4.0,
numeric_list_field=[1, 2],
),
fo.Sample(
filepath="/path/to/image3.png",
numeric_field=None,
numeric_list_field=None,
),
]
)
#
# Compute the bounds of a numeric field
#
bounds = dataset.bounds("numeric_field")
print(bounds) # (min, max)
#
# Compute the bounds of a numeric list field
#
bounds = dataset.bounds("numeric_list_field")
print(bounds) # (min, max)
#
# Compute the bounds of a transformation of a numeric field
#
bounds = dataset.bounds(2 * (F("numeric_field") + 1))
print(bounds) # (min, max)
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate. This can also
be a list or tuple of such arguments, in which case a tuple of
corresponding aggregation results (each receiving the same
additional keyword arguments, if any) will be returned
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **safe** (*False*) – whether to ignore nan/inf values when dealing with
floating point values
* **Returns:**
the `(min, max)` bounds
#### *property* camera_intrinsics
The camera intrinsics of the underlying dataset.
See [`fiftyone.core.dataset.Dataset.camera_intrinsics()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.camera_intrinsics) for more
information.
#### *property* classes
The classes of the underlying dataset.
See [`fiftyone.core.dataset.Dataset.classes()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.classes) for more information.
#### clear()
Deletes all samples in the view from the underlying dataset.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### clear_frame_field(field_name)
Clears the values of the frame-level field from all samples in the
view.
The field will remain in the dataset’s frame schema, and all frames in
the view will have the value `None` for the field.
You can use dot notation (`embedded.field.name`) to clear embedded
frame fields.
Only applicable to views that contain videos.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### WARNING
If the field name you specify is an embedded field, be aware that
this operation will save the entire top-level field after clearing
the field, which may result in data modification/loss if this view
modifies the field in any other ways.
* **Parameters:**
**field_name** – the field name or `embedded.field.name`
#### clear_frame_fields(field_names)
Clears the values of the frame-level fields from all samples in the
view.
The fields will remain in the dataset’s frame schema, and all frames in
the view will have the value `None` for the fields.
You can use dot notation (`embedded.field.name`) to clear embedded
frame fields.
Only applicable to views that contain videos.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### WARNING
If any of the field names you specify are embedded fields, be aware
that this operation will save the entire top-level field after
clearing the fields, which may result in data modification/loss if
this view modifies these fields in any other ways.
* **Parameters:**
**field_names** – the field name or iterable of field names
#### clear_frames()
Deletes all frame labels from the samples in the view from the
underlying dataset.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### clear_sample_field(field_name)
Clears the values of the field from all samples in the view.
The field will remain in the dataset’s schema, and all samples in the
view will have the value `None` for the field.
You can use dot notation (`embedded.field.name`) to clear embedded
fields.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### WARNING
If the field name you specify is an embedded field, be aware that
this operation will save the entire top-level field after clearing
the field, which may result in data modification/loss if this view
modifies the field in any other ways.
* **Parameters:**
**field_name** – the field name or `embedded.field.name`
#### clear_sample_fields(field_names)
Clears the values of the fields from all samples in the view.
The fields will remain in the dataset’s schema, and all samples in the
view will have the value `None` for the fields.
You can use dot notation (`embedded.field.name`) to clear embedded
fields.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### WARNING
If any of the field names you specify are embedded fields, be aware
that this operation will save the entire top-level field after
clearing the fields, which may result in data modification/loss if
this view modifies these fields in any other ways.
* **Parameters:**
**field_names** – the field name or iterable of field names
#### clone(name=None, persistent=False, include_indexes=False)
Creates a new dataset containing a copy of the contents of the view.
Dataset clones contain deep copies of all samples and dataset-level
information in the source collection. The source *media files*,
however, are not copied.
* **Parameters:**
* **name** (*None*) – a name for the cloned dataset. By default,
`get_default_dataset_name()` is used
* **persistent** (*False*) – whether the cloned dataset should be persistent
* **include_indexes** (*False*) – whether to recreate any custom indexes on
the new dataset (True) or a list of specific indexes or index
prefixes to recreate. By default, no custom indexes are
recreated
* **Returns:**
the new [`fiftyone.core.dataset.Dataset`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset)
#### clone_frame_field(field_name, new_field_name)
Clones the frame-level field of the view into a new field.
You can use dot notation (`embedded.field.name`) to clone embedded
frame fields.
Only applicable to views that contain videos.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### WARNING
If `new_field_name` is an embedded field, be aware that this
operation will save the entire top-level field of
`new_field_name` after performing the clone, which may result in
data modification/loss if this view modifies this field in any
other ways.
* **Parameters:**
* **field_name** – the field name or `embedded.field.name`
* **new_field_name** – the new field name or `embedded.field.name`
#### clone_frame_fields(field_mapping)
Clones the frame-level fields of the view into new frame-level
fields of the dataset.
You can use dot notation (`embedded.field.name`) to clone embedded
frame fields.
Only applicable to views that contain videos.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### WARNING
If any of the new field names to specify are embedded fields, be
aware that this operation will save the entire top-level new
fields after performing the clone, which may result in data
modification/loss if this view modifies these fields in any other
ways.
* **Parameters:**
**field_mapping** – a dict mapping field names to new field names into
which to clone each field
#### clone_sample_field(field_name, new_field_name)
Clones the given sample field of the view into a new field of the
dataset.
You can use dot notation (`embedded.field.name`) to clone embedded
fields.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### WARNING
If `new_field_name` is an embedded field, be aware that this
operation will save the entire top-level field of
`new_field_name` after performing the clone, which may result in
data modification/loss if this view modifies this field in any
other ways.
* **Parameters:**
* **field_name** – the field name or `embedded.field.name`
* **new_field_name** – the new field name or `embedded.field.name`
#### clone_sample_fields(field_mapping)
Clones the given sample fields of the view into new fields of the
dataset.
You can use dot notation (`embedded.field.name`) to clone embedded
fields.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### WARNING
If any of the new field names to specify are embedded fields, be
aware that this operation will save the entire top-level new
fields after performing the clone, which may result in data
modification/loss if this view modifies these fields in any other
ways.
* **Parameters:**
**field_mapping** – a dict mapping field names to new field names into
which to clone each field
#### compute_embeddings(model, embeddings_field=None, batch_size=None, num_workers=None, skip_failures=True, progress=None, \*\*kwargs)
Computes embeddings for the samples in the collection using the
given model.
This method supports all the following cases:
- Using an image model to compute embeddings for an image collection
- Using an image model to compute frame embeddings for a video
collection
- Using a video model to compute embeddings for a video collection
The `model` must expose embeddings, i.e.,
[`fiftyone.core.models.Model.has_embeddings()`](fiftyone.core.models.md#fiftyone.core.models.Model.has_embeddings) must return `True`.
If an `embeddings_field` is provided, the embeddings are saved to the
samples; otherwise, the embeddings are returned in-memory.
* **Parameters:**
* **model** – a [`fiftyone.core.models.Model`](fiftyone.core.models.md#fiftyone.core.models.Model), Hugging Face
Transformers model, Ultralytics model, SuperGradients model, or
Lightning Flash model
* **embeddings_field** (*None*) – the name of a field in which to store the
embeddings. When computing video frame embeddings, the
“frames.” prefix is optional
* **batch_size** (*None*) – an optional batch size to use, if the model
supports batching
* **num_workers** (*None*) – the number of workers for the
[`torch.utils.data.DataLoader`](https://docs.pytorch.org/docs/stable/data.html#torch.utils.data.DataLoader) to use. Only
applicable for Torch-based models
* **skip_failures** (*True*) – whether to gracefully continue without
raising an error if embeddings cannot be generated for a
sample. Only applicable to [`fiftyone.core.models.Model`](fiftyone.core.models.md#fiftyone.core.models.Model)
instances
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **\*\*kwargs** – optional model-specific keyword arguments passed through
to the underlying inference implementation
* **Returns:**
- `None`, if an `embeddings_field` is provided
- a `num_samples x num_dim` array of embeddings, when computing
embeddings for image/video collections with image/video models,
respectively, and no `embeddings_field` is provided. If
`skip_failures` is `True` and any errors are detected, a
list of length `num_samples` is returned instead containing
all successfully computed embedding vectors along with `None`
entries for samples for which embeddings could not be computed
- a dictionary mapping sample IDs to `num_frames x num_dim`
arrays of embeddings, when computing frame embeddings for video
collections using an image model. If `skip_failures` is
`True` and any errors are detected, the values of this
dictionary will contain arrays of embeddings for all frames
1, 2, … until the error occurred, or `None` if no
embeddings were computed at all
* **Return type:**
one of the following
#### compute_metadata(overwrite=False, num_workers=None, skip_failures=True, warn_failures=True, progress=None)
Populates the `metadata` field of all samples in the collection.
Any samples with existing metadata are skipped, unless
`overwrite == True`.
* **Parameters:**
* **overwrite** (*False*) – whether to overwrite existing metadata
* **num_workers** (*None*) – a suggested number of threads to use
* **skip_failures** (*True*) – whether to gracefully continue without
raising an error if metadata cannot be computed for a sample
* **warn_failures** (*True*) – whether to log a warning if metadata cannot
be computed for a sample
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
#### compute_patch_embeddings(model, patches_field, embeddings_field=None, force_square=False, alpha=None, handle_missing='skip', batch_size=None, num_workers=None, skip_failures=True, progress=None)
Computes embeddings for the image patches defined by
`patches_field` of the samples in the collection using the given
model.
This method supports all the following cases:
- Using an image model to compute patch embeddings for an image
collection
- Using an image model to compute frame patch embeddings for a video
collection
The `model` must expose embeddings, i.e.,
[`fiftyone.core.models.Model.has_embeddings()`](fiftyone.core.models.md#fiftyone.core.models.Model.has_embeddings) must return `True`.
If an `embeddings_field` is provided, the embeddings are saved to the
samples; otherwise, the embeddings are returned in-memory.
* **Parameters:**
* **model** – a [`fiftyone.core.models.Model`](fiftyone.core.models.md#fiftyone.core.models.Model), Hugging Face
Transformers model, Ultralytics model, SuperGradients model,
or Lightning Flash model
* **patches_field** – the name of the field defining the image patches in
each sample to embed. Must be of type
[`fiftyone.core.labels.Detection`](fiftyone.core.labels.md#fiftyone.core.labels.Detection),
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections),
[`fiftyone.core.labels.Polyline`](fiftyone.core.labels.md#fiftyone.core.labels.Polyline), or
[`fiftyone.core.labels.Polylines`](fiftyone.core.labels.md#fiftyone.core.labels.Polylines). When computing video
frame embeddings, the “frames.” prefix is optional
* **embeddings_field** (*None*) – the name of a label attribute in which to
store the embeddings
* **force_square** (*False*) – whether to minimally manipulate the patch
bounding boxes into squares prior to extraction
* **alpha** (*None*) – an optional expansion/contraction to apply to the
patches before extracting them, in `[-1, inf)`. If provided,
the length and width of the box are expanded (or contracted,
when `alpha < 0`) by `(100 * alpha)%`. For example, set
`alpha = 0.1` to expand the boxes by 10%, and set
`alpha = -0.1` to contract the boxes by 10%
* **handle_missing** ( *"skip"*) –
how to handle images with no patches.
Supported values are:
- ”skip”: skip the image and assign its embedding as `None`
- ”image”: use the whole image as a single patch
- ”error”: raise an error
* **batch_size** (*None*) – an optional batch size to use, if the model
supports batching
* **num_workers** (*None*) – the number of workers for the
[`torch.utils.data.DataLoader`](https://docs.pytorch.org/docs/stable/data.html#torch.utils.data.DataLoader) to use. Only
applicable for Torch-based models
* **skip_failures** (*True*) – whether to gracefully continue without
raising an error if embeddings cannot be generated for a sample
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **Returns:**
- `None`, if an `embeddings_field` is provided
- a dict mapping sample IDs to `num_patches x num_dim` arrays
of patch embeddings, when computing patch embeddings for image
collections and no `embeddings_field` is provided. If
`skip_failures` is `True` and any errors are detected, this
dictionary will contain `None` values for any samples for
which embeddings could not be computed
- a dict of dicts mapping sample IDs to frame numbers to
`num_patches x num_dim` arrays of patch embeddings, when
computing patch embeddings for the frames of video collections
and no `embeddings_field` is provided. If `skip_failures`
is `True` and any errors are detected, this nested dict will
contain missing or `None` values to indicate uncomputable
embeddings
* **Return type:**
one of the following
#### concat(samples)
Concatenates the contents of the given `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)
view = view1.concat(view2)
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:]
patches = patches1.concat(patches2)
print(patches1)
print(patches2)
print(patches)
```
* **Parameters:**
**samples** – a `SampleCollection` whose contents to append to
this collection
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### count(field_or_expr=None, expr=None, safe=False)
Counts the number of field values in the collection.
`None`-valued fields are ignored.
If no field is provided, the samples themselves are counted.
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"),
fo.Detection(label="dog"),
]
),
),
fo.Sample(
filepath="/path/to/image2.png",
predictions=fo.Detections(
detections=[
fo.Detection(label="cat"),
fo.Detection(label="rabbit"),
fo.Detection(label="squirrel"),
]
),
),
fo.Sample(
filepath="/path/to/image3.png",
predictions=None,
),
]
)
#
# Count the number of samples in the dataset
#
count = dataset.count()
print(count) # the count
#
# Count the number of samples with `predictions`
#
count = dataset.count("predictions")
print(count) # the count
#
# Count the number of objects in the `predictions` field
#
count = dataset.count("predictions.detections")
print(count) # the count
#
# Count the number of objects in samples with > 2 predictions
#
count = dataset.count(
(F("predictions.detections").length() > 2).if_else(
F("predictions.detections"), None
)
)
print(count) # the count
```
* **Parameters:**
* **field_or_expr** (*None*) –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate. If neither
`field_or_expr` or `expr` is provided, the samples
themselves are counted. This can also be a list or tuple of
such arguments, in which case a tuple of corresponding
aggregation results (each receiving the same additional keyword
arguments, if any) will be returned
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **safe** (*False*) – whether to ignore nan/inf values when dealing with
floating point values
* **Returns:**
the count
#### count_label_tags(label_fields=None)
Counts the occurrences of all label tags in the specified label
field(s) of this collection.
* **Parameters:**
**label_fields** (*None*) – an optional name or iterable of names of
[`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) fields. By default, all
label fields are used
* **Returns:**
a dict mapping tags to counts
#### count_sample_tags()
Counts the occurrences of sample tags in this collection.
* **Returns:**
a dict mapping tags to counts
#### count_values(field_or_expr, expr=None, safe=False)
Counts the occurrences of field values in the collection.
This aggregation is typically applied to *countable* field types (or
lists of such types):
- [`fiftyone.core.fields.BooleanField`](fiftyone.core.fields.md#fiftyone.core.fields.BooleanField)
- [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField)
- [`fiftyone.core.fields.StringField`](fiftyone.core.fields.md#fiftyone.core.fields.StringField)
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",
tags=["sunny"],
predictions=fo.Detections(
detections=[
fo.Detection(label="cat"),
fo.Detection(label="dog"),
]
),
),
fo.Sample(
filepath="/path/to/image2.png",
tags=["cloudy"],
predictions=fo.Detections(
detections=[
fo.Detection(label="cat"),
fo.Detection(label="rabbit"),
]
),
),
fo.Sample(
filepath="/path/to/image3.png",
predictions=None,
),
]
)
#
# Compute the tag counts in the dataset
#
counts = dataset.count_values("tags")
print(counts) # dict mapping values to counts
#
# Compute the predicted label counts in the dataset
#
counts = dataset.count_values("predictions.detections.label")
print(counts) # dict mapping values to counts
#
# Compute the predicted label counts after some normalization
#
counts = dataset.count_values(
F("predictions.detections.label").map_values(
{"cat": "pet", "dog": "pet"}
).upper()
)
print(counts) # dict mapping values to counts
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate. This can also
be a list or tuple of such arguments, in which case a tuple of
corresponding aggregation results (each receiving the same
additional keyword arguments, if any) will be returned
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **safe** (*False*) – whether to treat nan/inf values as None when dealing
with floating point values
* **Returns:**
a dict mapping values to counts
#### create_index(field_or_spec, unique=False, force=False, wait=True, \*\*kwargs)
Creates an index on the given field or with the given specification,
if necessary.
Indexes enable efficient sorting, merging, and other such operations.
Frame-level fields can be indexed by prepending `"frames."` to the
field name.
#### NOTE
If a matching non-unique index exists and you request a unique
index, the existing index will be converted to a unique index.
If a matching unique index exists and you request a non-unique
index, the existing index will **only** be converted to a
non-unique index if you specify `force=True`.
#### NOTE
If an index with the same field(s) but different order(s) already
exists, the existing index will **only** be replaced with a new
index if you specify `force=True`.
* **Parameters:**
* **field_or_spec** – the field name, `embedded.field.name`, or index
specification list. See
[`pymongo.collection.Collection.create_index()`](https://pymongo.readthedocs.io/en/stable/api/pymongo/collection.html#pymongo.collection.Collection.create_index) for
supported values
* **unique** (*False*) – whether to add a uniqueness constraint to the index
* **force** (*False*) – whether to convert an existing unique index to a
non-unique index or replace an existing index with different
orderings with a new index. By default, existing indexes will
not be modified in these cases
* **wait** (*True*) – whether to wait for index creation to finish
* **\*\*kwargs** – optional keyword arguments for
[`pymongo.collection.Collection.create_index()`](https://pymongo.readthedocs.io/en/stable/api/pymongo/collection.html#pymongo.collection.Collection.create_index)
* **Returns:**
the name of the index
#### *property* dataset_name
The name of the underlying dataset.
#### *property* default_classes
The default classes of the underlying dataset.
See [`fiftyone.core.dataset.Dataset.default_classes()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.default_classes) for more
information.
#### *property* default_group_slice
The default group slice of the view, or None if the view is not
grouped.
#### *property* default_mask_targets
The default mask targets of the underlying dataset.
See [`fiftyone.core.dataset.Dataset.default_mask_targets()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.default_mask_targets) for more
information.
#### *property* default_skeleton
The default keypoint skeleton of the underlying dataset.
See [`fiftyone.core.dataset.Dataset.default_skeleton()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.default_skeleton) for more
information.
#### delete_annotation_run(anno_key)
Deletes the annotation run with the given key from this collection.
Calling this method only deletes the **record** of the annotation run
from the collection; it will not delete any annotations loaded onto
your dataset via [`load_annotations()`](#fiftyone.core.clips.TrajectoriesView.load_annotations), nor will it delete any
associated information from the annotation backend.
Use [`load_annotation_results()`](#fiftyone.core.clips.TrajectoriesView.load_annotation_results) to programmatically manage/delete
a run from the annotation backend.
* **Parameters:**
**anno_key** – an annotation key
#### delete_annotation_runs()
Deletes all annotation runs from this collection.
Calling this method only deletes the **records** of the annotation runs
from this collection; it will not delete any annotations loaded onto
your dataset via [`load_annotations()`](#fiftyone.core.clips.TrajectoriesView.load_annotations), nor will it delete any
associated information from the annotation backend.
Use [`load_annotation_results()`](#fiftyone.core.clips.TrajectoriesView.load_annotation_results) to programmatically manage/delete
runs in the annotation backend.
#### delete_brain_run(brain_key)
Deletes the brain method run with the given key from this
collection.
* **Parameters:**
**brain_key** – a brain key
#### delete_brain_runs()
Deletes all brain method runs from this collection.
#### delete_evaluation(eval_key)
Deletes the evaluation results associated with the given evaluation
key from this collection.
* **Parameters:**
**eval_key** – an evaluation key
#### delete_evaluations()
Deletes all evaluation results from this collection.
#### delete_run(run_key)
Deletes the run with the given key from this collection.
* **Parameters:**
**run_key** – a run key
#### delete_runs()
Deletes all runs from this collection.
#### *property* description
A description of the underlying dataset.
See [`fiftyone.core.dataset.Dataset.description()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.description) for more
information.
#### distinct(field_or_expr, expr=None, safe=False)
Computes the distinct values of a field in the collection.
`None`-valued fields are ignored.
This aggregation is typically applied to *countable* field types (or
lists of such types):
- [`fiftyone.core.fields.BooleanField`](fiftyone.core.fields.md#fiftyone.core.fields.BooleanField)
- [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField)
- [`fiftyone.core.fields.StringField`](fiftyone.core.fields.md#fiftyone.core.fields.StringField)
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",
tags=["sunny"],
predictions=fo.Detections(
detections=[
fo.Detection(label="cat"),
fo.Detection(label="dog"),
]
),
),
fo.Sample(
filepath="/path/to/image2.png",
tags=["sunny", "cloudy"],
predictions=fo.Detections(
detections=[
fo.Detection(label="cat"),
fo.Detection(label="rabbit"),
]
),
),
fo.Sample(
filepath="/path/to/image3.png",
predictions=None,
),
]
)
#
# Get the distinct tags in a dataset
#
values = dataset.distinct("tags")
print(values) # list of distinct values
#
# Get the distinct predicted labels in a dataset
#
values = dataset.distinct("predictions.detections.label")
print(values) # list of distinct values
#
# Get the distinct predicted labels after some normalization
#
values = dataset.distinct(
F("predictions.detections.label").map_values(
{"cat": "pet", "dog": "pet"}
).upper()
)
print(values) # list of distinct values
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate. This can also
be a list or tuple of such arguments, in which case a tuple of
corresponding aggregation results (each receiving the same
additional keyword arguments, if any) will be returned
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **safe** (*False*) – whether to ignore nan/inf values when dealing with
floating point values
* **Returns:**
a sorted list of distinct values
#### draw_labels(output_dir, rel_dir=None, label_fields=None, overwrite=False, config=None, progress=None, \*\*kwargs)
Renders annotated versions of the media in the collection with the
specified label data overlaid to the given directory.
The filenames of the sample media are maintained, unless a name
conflict would occur in `output_dir`, in which case an index of the
form `"-%d" % count` is appended to the base filename.
Images are written in format `fo.config.default_image_ext`, and
videos are written in format `fo.config.default_video_ext`.
* **Parameters:**
* **output_dir** – the directory to write the annotated media
* **rel_dir** (*None*) – an optional relative directory to strip from each
input filepath to generate a unique identifier that is joined
with `output_dir` to generate an output path for each
annotated media. This argument allows for populating nested
subdirectories in `output_dir` that match the shape of the
input paths. The path is converted to an absolute path (if
necessary) via [`fiftyone.core.storage.normalize_path()`](fiftyone.core.storage.md#fiftyone.core.storage.normalize_path)
* **label_fields** (*None*) – a label field or list of label fields to
render. By default, all [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label)
fields are drawn
* **overwrite** (*False*) – whether to delete `output_dir` if it exists
before rendering
* **config** (*None*) – an optional
[`fiftyone.utils.annotations.DrawConfig`](fiftyone.utils.annotations.md#fiftyone.utils.annotations.DrawConfig) configuring how
to draw the labels
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **\*\*kwargs** – optional keyword arguments specifying parameters of the
default [`fiftyone.utils.annotations.DrawConfig`](fiftyone.utils.annotations.md#fiftyone.utils.annotations.DrawConfig) to
override
* **Returns:**
the list of paths to the rendered media
#### drop_index(field_or_name)
Drops the index for the given field or name, if necessary.
* **Parameters:**
**field_or_name** – a field name, `embedded.field.name`, or compound
index name. Use [`list_indexes()`](#fiftyone.core.clips.TrajectoriesView.list_indexes) to see the available
indexes
#### ensure_frames()
Ensures that the video view contains frame instances for every frame
of each sample’s source video.
Empty frames will be inserted for missing frames, and already existing
frames are left unchanged.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### evaluate_classifications(pred_field, gt_field='ground_truth', eval_key=None, classes=None, missing=None, method=None, progress=None, \*\*kwargs)
Evaluates the classification predictions in this collection with
respect to the specified ground truth labels.
By default, this method simply compares the ground truth and prediction
for each sample, but other strategies such as binary evaluation and
top-k matching can be configured via the `method` parameter.
You can customize the evaluation method by passing additional
parameters for the method’s config class as `kwargs`.
The natively provided `method` values and their associated configs
are:
- `"simple"`: [`fiftyone.utils.eval.classification.SimpleEvaluationConfig`](fiftyone.utils.eval.classification.md#fiftyone.utils.eval.classification.SimpleEvaluationConfig)
- `"top-k"`: [`fiftyone.utils.eval.classification.TopKEvaluationConfig`](fiftyone.utils.eval.classification.md#fiftyone.utils.eval.classification.TopKEvaluationConfig)
- `"binary"`: [`fiftyone.utils.eval.classification.BinaryEvaluationConfig`](fiftyone.utils.eval.classification.md#fiftyone.utils.eval.classification.BinaryEvaluationConfig)
If an `eval_key` is specified, then this method will record some
statistics on each sample:
- When evaluating sample-level fields, an `eval_key` field will be
populated on each sample recording whether that sample’s prediction
is correct.
- When evaluating frame-level fields, an `eval_key` field will be
populated on each frame recording whether that frame’s prediction
is correct. In addition, an `eval_key` field will be populated on
each sample that records the average accuracy of the frame
predictions of the sample.
* **Parameters:**
* **pred_field** – the name of the field containing the predicted
[`fiftyone.core.labels.Classification`](fiftyone.core.labels.md#fiftyone.core.labels.Classification) instances
* **gt_field** ( *"ground_truth"*) – the name of the field containing the
ground truth [`fiftyone.core.labels.Classification`](fiftyone.core.labels.md#fiftyone.core.labels.Classification)
instances
* **eval_key** (*None*) – a string key to use to refer to this evaluation
* **classes** (*None*) – the list of possible classes. If not provided,
the observed ground truth/predicted labels are used
* **missing** (*None*) – a missing label string. Any None-valued labels
are given this label for results purposes
* **method** (*None*) – a string specifying the evaluation method to use.
The supported values are
`fo.evaluation_config.classification_backends.keys()` and the
default is `fo.evaluation_config.classification_default_backend`
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **\*\*kwargs** – optional keyword arguments for the constructor of the
[`fiftyone.utils.eval.classification.ClassificationEvaluationConfig`](fiftyone.utils.eval.classification.md#fiftyone.utils.eval.classification.ClassificationEvaluationConfig)
being used
* **Returns:**
a [`fiftyone.utils.eval.classification.ClassificationResults`](fiftyone.utils.eval.classification.md#fiftyone.utils.eval.classification.ClassificationResults)
#### evaluate_detections(pred_field, gt_field='ground_truth', eval_key=None, classes=None, missing=None, method=None, iou=0.5, use_masks=False, use_boxes=False, classwise=True, dynamic=True, progress=None, \*\*kwargs)
Evaluates the specified predicted detections in this collection with
respect to the specified ground truth detections.
This method supports evaluating the following spatial data types:
- Object detections in [`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) format
- Instance segmentations in [`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections)
format with their `mask` attributes populated
- Polygons in [`fiftyone.core.labels.Polylines`](fiftyone.core.labels.md#fiftyone.core.labels.Polylines) format
- Keypoints in [`fiftyone.core.labels.Keypoints`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoints) format
- Temporal detections in
[`fiftyone.core.labels.TemporalDetections`](fiftyone.core.labels.md#fiftyone.core.labels.TemporalDetections) format
For spatial object detection evaluation, this method uses COCO-style
evaluation by default.
When evaluating keypoints, “IoUs” are computed via
[object keypoint similarity](https://cocodataset.org/#keypoints-eval).
You can pass `keypoint_sigmas` to customize the per-keypoint OKS
falloff.
For temporal segment detection, this method uses ActivityNet-style
evaluation by default.
You can use the `method` parameter to select a different method, and
you can optionally customize the method by passing additional
parameters for the method’s config class as `kwargs`.
The natively provided `method` values and their associated configs
are:
- `"coco"`: [`fiftyone.utils.eval.coco.COCOEvaluationConfig`](fiftyone.utils.eval.coco.md#fiftyone.utils.eval.coco.COCOEvaluationConfig)
- `"open-images"`: [`fiftyone.utils.eval.openimages.OpenImagesEvaluationConfig`](fiftyone.utils.eval.openimages.md#fiftyone.utils.eval.openimages.OpenImagesEvaluationConfig)
- `"activitynet"`: [`fiftyone.utils.eval.activitynet.ActivityNetEvaluationConfig`](fiftyone.utils.eval.activitynet.md#fiftyone.utils.eval.activitynet.ActivityNetEvaluationConfig)
If an `eval_key` is provided, a number of fields are populated at the
object- and sample-level recording the results of the evaluation:
- True positive (TP), false positive (FP), and false negative (FN)
counts for the each sample are saved in top-level fields of each
sample:
```default
TP: sample._tp
FP: sample._fp
FN: sample._fn
```
In addition, when evaluating frame-level objects, TP/FP/FN counts
are recorded for each frame:
```default
TP: frame._tp
FP: frame._fp
FN: frame._fn
```
- The fields listed below are populated on each individual object;
these fields tabulate the TP/FP/FN status of the object, the ID of
the matching object (if any), and the matching IoU:
```default
TP/FP/FN: object.
ID: object._id
IoU: object._iou
```
* **Parameters:**
* **pred_field** – the name of the field containing the predicted
[`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),
or [`fiftyone.core.labels.TemporalDetections`](fiftyone.core.labels.md#fiftyone.core.labels.TemporalDetections)
* **gt_field** ( *"ground_truth"*) – the name of the field containing the
ground truth [`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),
or [`fiftyone.core.labels.TemporalDetections`](fiftyone.core.labels.md#fiftyone.core.labels.TemporalDetections)
* **eval_key** (*None*) – a string key to use to refer to this evaluation
* **classes** (*None*) – the list of possible classes. If not provided,
the observed ground truth/predicted labels are used
* **missing** (*None*) – a missing label string. Any unmatched objects are
given this label for results purposes
* **method** (*None*) – a string specifying the evaluation method to use.
The supported values are
`fo.evaluation_config.detection_backends.keys()` and the
default is `fo.evaluation_config.detection_default_backend`
* **iou** (*0.50*) – the IoU threshold to use to determine matches
* **use_masks** (*False*) – whether to compute IoUs using the instances
masks in the `mask` attribute of the provided objects, which
must be [`fiftyone.core.labels.Detection`](fiftyone.core.labels.md#fiftyone.core.labels.Detection) instances
* **use_boxes** (*False*) – whether to compute IoUs using the bounding boxes
of the provided [`fiftyone.core.labels.Polyline`](fiftyone.core.labels.md#fiftyone.core.labels.Polyline)
instances rather than using their actual geometries
* **classwise** (*True*) – whether to only match objects with the same class
label (True) or allow matches between classes (False)
* **dynamic** (*True*) – whether to declare the dynamic object-level
attributes that are populated on the dataset’s schema
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **\*\*kwargs** – optional keyword arguments for the constructor of the
[`fiftyone.utils.eval.detection.DetectionEvaluationConfig`](fiftyone.utils.eval.detection.md#fiftyone.utils.eval.detection.DetectionEvaluationConfig)
being used
* **Returns:**
a [`fiftyone.utils.eval.detection.DetectionResults`](fiftyone.utils.eval.detection.md#fiftyone.utils.eval.detection.DetectionResults)
#### evaluate_regressions(pred_field, gt_field='ground_truth', eval_key=None, missing=None, method=None, progress=None, \*\*kwargs)
Evaluates the regression predictions in this collection with respect
to the specified ground truth values.
You can customize the evaluation method by passing additional
parameters for the method’s config class as `kwargs`.
The natively provided `method` values and their associated configs
are:
- `"simple"`: [`fiftyone.utils.eval.regression.SimpleEvaluationConfig`](fiftyone.utils.eval.regression.md#fiftyone.utils.eval.regression.SimpleEvaluationConfig)
If an `eval_key` is specified, then this method will record some
statistics on each sample:
- When evaluating sample-level fields, an `eval_key` field will be
populated on each sample recording the error of that sample’s
prediction.
- When evaluating frame-level fields, an `eval_key` field will be
populated on each frame recording the error of that frame’s
prediction. In addition, an `eval_key` field will be populated on
each sample that records the average error of the frame predictions
of the sample.
* **Parameters:**
* **pred_field** – the name of the field containing the predicted
[`fiftyone.core.labels.Regression`](fiftyone.core.labels.md#fiftyone.core.labels.Regression) instances
* **gt_field** ( *"ground_truth"*) – the name of the field containing the
ground truth [`fiftyone.core.labels.Regression`](fiftyone.core.labels.md#fiftyone.core.labels.Regression) instances
* **eval_key** (*None*) – a string key to use to refer to this evaluation
* **missing** (*None*) – a missing value. Any None-valued regressions are
given this value for results purposes
* **method** (*None*) – a string specifying the evaluation method to use.
The supported values are
`fo.evaluation_config.regression_backends.keys()` and the
default is `fo.evaluation_config.regression_default_backend`
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **\*\*kwargs** – optional keyword arguments for the constructor of the
[`fiftyone.utils.eval.regression.RegressionEvaluationConfig`](fiftyone.utils.eval.regression.md#fiftyone.utils.eval.regression.RegressionEvaluationConfig)
being used
* **Returns:**
a [`fiftyone.utils.eval.regression.RegressionResults`](fiftyone.utils.eval.regression.md#fiftyone.utils.eval.regression.RegressionResults)
#### evaluate_segmentations(pred_field, gt_field='ground_truth', eval_key=None, mask_targets=None, method=None, progress=None, \*\*kwargs)
Evaluates the specified semantic segmentation masks in this
collection with respect to the specified ground truth masks.
If the size of a predicted mask does not match the ground truth mask,
it is resized to match the ground truth.
By default, this method simply performs pixelwise evaluation of the
full masks, but other strategies such as boundary-only evaluation can
be configured by passing additional parameters for the method’s
config class as `kwargs`.
The natively provided `method` values and their associated configs
are:
- `"simple"`: [`fiftyone.utils.eval.segmentation.SimpleEvaluationConfig`](fiftyone.utils.eval.segmentation.md#fiftyone.utils.eval.segmentation.SimpleEvaluationConfig)
If an `eval_key` is provided, the accuracy, precision, and recall of
each sample is recorded in top-level fields of each sample:
```default
Accuracy: sample._accuracy
Precision: sample._precision
Recall: sample._recall
```
In addition, when evaluating frame-level masks, the accuracy,
precision, and recall of each frame if recorded in the following
frame-level fields:
```default
Accuracy: frame._accuracy
Precision: frame._precision
Recall: frame._recall
```
#### NOTE
The mask values `0` and `#000000` are treated as a background
class for the purposes of computing evaluation metrics like
precision and recall.
* **Parameters:**
* **pred_field** – the name of the field containing the predicted
[`fiftyone.core.labels.Segmentation`](fiftyone.core.labels.md#fiftyone.core.labels.Segmentation) instances
* **gt_field** ( *"ground_truth"*) – the name of the field containing the
ground truth [`fiftyone.core.labels.Segmentation`](fiftyone.core.labels.md#fiftyone.core.labels.Segmentation)
instances
* **eval_key** (*None*) – a string key to use to refer to this evaluation
* **mask_targets** (*None*) – a dict mapping pixel values (2D masks) or RGB
hex strings (3D masks) to semantic label strings. If not
provided, the observed values are used as labels
* **method** (*None*) – a string specifying the evaluation method to use.
The supported values are
`fo.evaluation_config.segmentation_backends.keys()` and the
default is `fo.evaluation_config.segmentation_default_backend`
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **\*\*kwargs** – optional keyword arguments for the constructor of the
[`fiftyone.utils.eval.segmentation.SegmentationEvaluationConfig`](fiftyone.utils.eval.segmentation.md#fiftyone.utils.eval.segmentation.SegmentationEvaluationConfig)
being used
* **Returns:**
a [`fiftyone.utils.eval.segmentation.SegmentationResults`](fiftyone.utils.eval.segmentation.md#fiftyone.utils.eval.segmentation.SegmentationResults)
#### exclude(sample_ids)
Excludes the samples with the given IDs from the 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
view = dataset.exclude(sample_id)
#
# Exclude the first and last samples from the dataset
#
sample_ids = [dataset.first().id, dataset.last().id]
view = dataset.exclude(sample_ids)
```
* **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)
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### exclude_by(field, values)
Excludes the samples with the given field values from the
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.clips.TrajectoriesView.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
#
view = dataset.exclude_by("int", [1, 9, 3, 7, 5])
print(view.head(5))
#
# Create a view excluding samples whose `str` field have the given
# values
#
view = dataset.exclude_by("str", ["1", "9", "3", "7", "5"])
print(view.head(5))
```
* **Parameters:**
* **field** – a field or `embedded.field.name`
* **values** – a value or iterable of values to exclude by
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### exclude_fields(field_names=None, meta_filter=None, \_allow_missing=False)
Excludes the fields with the given names from the samples in the
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
#
view = dataset.exclude_fields("predictions")
#
# Exclude the `mood` attribute from all classifications in the
# `predictions` field
#
view = dataset.exclude_fields("predictions.mood")
```
* **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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### exclude_frames(frame_ids, omit_empty=True)
Excludes the frames with the given IDs from the 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,
]
view = dataset.exclude_frames(frame_ids)
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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### exclude_group_slices(slices=None, media_type=None)
Excludes the specified group slice(s) from the 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 samples from the "ego" group slice
#
view = dataset.exclude_group_slices("ego")
#
# Exclude the samples from the "left" or "right" group slices
#
view = dataset.exclude_group_slices(["left", "right"])
#
# Exclude all image slices
#
view = dataset.exclude_group_slices(media_type="image")
```
* **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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### exclude_groups(group_ids)
Excludes the groups with the given IDs from the 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")
other_groups = dataset.exclude_groups(group_ids)
assert len(set(group_ids) & set(other_groups.values("group.id"))) == 0
```
* **Parameters:**
**groups_ids** –
the groups to exclude. 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)
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### exclude_labels(labels=None, ids=None, instance_ids=None, tags=None, fields=None, omit_empty=True)
Excludes the specified labels from the 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...
view = dataset.exclude_labels(labels=session.selected_labels)
#
# Exclude labels with the specified IDs
#
# Grab some label IDs
ids = [
dataset.first().ground_truth.detections[0].id,
dataset.last().predictions.detections[0].id,
]
view = dataset.exclude_labels(ids=ids)
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
view = dataset.exclude_labels(tags="test")
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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### exists(field, bool=None)
Returns a view containing the samples in the 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
#
view = dataset.exists("predictions")
#
# Only include samples that do NOT have a value in their
# `predictions` field
#
view = dataset.exists("predictions", False)
#
# Only include samples that have prediction confidences
#
view = dataset.exists("predictions.confidence")
```
* **Parameters:**
* **field** – the field name or `embedded.field.name`
* **bool** (*None*) – whether to check if the field exists (None or True) or
does not exist (False)
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### export(export_dir=None, dataset_type=None, data_path=None, labels_path=None, export_media=None, rel_dir=None, dataset_exporter=None, label_field=None, frame_labels_field=None, overwrite=False, progress=None, \*\*kwargs)
Exports the samples in the collection to disk.
You can perform exports with this method via the following basic
patterns:
1. Provide `export_dir` and `dataset_type` to export the content
to a directory in the default layout for the specified format, as
documented in [this page](../user_guide/export_datasets.md#exporting-datasets)
2. Provide `dataset_type` along with `data_path`, `labels_path`,
and/or `export_media` to directly specify where to export the
source media and/or labels (if applicable) in your desired format.
This syntax provides the flexibility to, for example, perform
workflows like labels-only exports
3. Provide a `dataset_exporter` to which to feed samples to perform
a fully-customized export
In all workflows, the remaining parameters of this method can be
provided to further configure the export.
See [this page](../user_guide/export_datasets.md#exporting-datasets) for more information about
the available export formats and examples of using this method.
See [this guide](../user_guide/export_datasets.md#custom-dataset-exporter) for more details about
exporting datasets in custom formats by defining your own
[`fiftyone.utils.data.exporters.DatasetExporter`](fiftyone.utils.data.exporters.md#fiftyone.utils.data.exporters.DatasetExporter).
This method will automatically coerce the data to match the requested
export in the following cases:
- When exporting in either an unlabeled image or image classification
format, if a spatial label field is provided
([`fiftyone.core.labels.Detection`](fiftyone.core.labels.md#fiftyone.core.labels.Detection),
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections),
[`fiftyone.core.labels.Polyline`](fiftyone.core.labels.md#fiftyone.core.labels.Polyline), or
[`fiftyone.core.labels.Polylines`](fiftyone.core.labels.md#fiftyone.core.labels.Polylines)), then the
**image patches** of the provided samples will be exported
- When exporting in labeled image dataset formats that expect
list-type labels ([`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), or
[`fiftyone.core.labels.Polylines`](fiftyone.core.labels.md#fiftyone.core.labels.Polylines)), if a label field contains
labels in non-list format
(e.g., [`fiftyone.core.labels.Classification`](fiftyone.core.labels.md#fiftyone.core.labels.Classification)), the labels
will be automatically upgraded to single-label lists
- When exporting in labeled image dataset formats that expect
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) labels, if a
[`fiftyone.core.labels.Classification`](fiftyone.core.labels.md#fiftyone.core.labels.Classification) field is provided, the
labels will be automatically upgraded to detections that span the
entire images
* **Parameters:**
* **export_dir** (*None*) –
the directory to which to export the samples in
format `dataset_type`. This parameter may be omitted if you
have provided appropriate values for the `data_path` and/or
`labels_path` parameters. Alternatively, this can also be an
archive path with one of the following extensions:
```default
.zip, .tar, .tar.gz, .tgz, .tar.bz, .tbz
```
If an archive path is specified, the export is performed in a
directory of same name (minus extension) and then automatically
archived and the directory then deleted
* **dataset_type** (*None*) – the [`fiftyone.types.Dataset`](fiftyone.types.md#fiftyone.types.Dataset) type to
write. If not specified, the default type for `label_field`
is used
* **data_path** (*None*) –
an optional parameter that enables explicit
control over the location of the exported media for certain
export formats. Can be any of the following:
- a folder name like `"data"` or `"data/"` specifying a
subfolder of `export_dir` in which to export the media
- an absolute directory path in which to export the media. In
this case, the `export_dir` has no effect on the location
of the data
- a filename like `"data.json"` specifying the filename of
a JSON manifest file in `export_dir` generated when
`export_media` is `"manifest"`
- an absolute filepath specifying the location to write the
JSON manifest file when `export_media` is `"manifest"`.
In this case, `export_dir` has no effect on the location
of the data
If None, a default value of this parameter will be chosen based
on the value of the `export_media` parameter. Note that this
parameter is not applicable to certain export formats such as
binary types like TF records
* **labels_path** (*None*) –
an optional parameter that enables explicit
control over the location of the exported labels. Only
applicable when exporting in certain labeled dataset formats.
Can be any of the following:
- a type-specific folder name like `"labels"` or
`"labels/"` or a filename like `"labels.json"` or
`"labels.xml"` specifying the location in `export_dir`
in which to export the labels
- an absolute directory or filepath in which to export the
labels. In this case, the `export_dir` has no effect on
the location of the labels
For labeled datasets, the default value of this parameter will
be chosen based on the export format so that the labels will be
exported into `export_dir`
* **export_media** (*None*) –
controls how to export the raw media. The
supported values are:
- `True`: copy all media files into the output directory
- `False`: don’t export media. This option is only useful
when exporting labeled datasets whose label format stores
sufficient information to locate the associated media
- `"move"`: move all media files into the output directory
- `"symlink"`: create symlinks to the media files in the
output directory
- `"manifest"`: create a `data.json` in the output
directory that maps UUIDs used in the labels files to the
filepaths of the source media, rather than exporting the
actual media
If None, an appropriate default value of this parameter will be
chosen based on the value of the `data_path` parameter. Note
that some dataset formats may not support certain values for
this parameter (e.g., when exporting in binary formats such as
TF records, “symlink” is not an option)
* **rel_dir** (*None*) – an optional relative directory to strip from each
input filepath to generate a unique identifier for each media.
When exporting media, this identifier is joined with
`data_path` to generate an output path for each exported
media. This argument allows for populating nested
subdirectories that match the shape of the input paths. The
path is converted to an absolute path (if necessary) via
[`fiftyone.core.storage.normalize_path()`](fiftyone.core.storage.md#fiftyone.core.storage.normalize_path)
* **dataset_exporter** (*None*) – a
[`fiftyone.utils.data.exporters.DatasetExporter`](fiftyone.utils.data.exporters.md#fiftyone.utils.data.exporters.DatasetExporter) to use
to export the samples. When provided, parameters such as
`export_dir`, `dataset_type`, `data_path`, and
`labels_path` have no effect
* **label_field** (*None*) –
controls the label field(s) to export. Only
applicable to labeled datasets. Can be any of the following:
- the name of a label field to export
- a glob pattern of label field(s) to export
- a list or tuple of label field(s) to export
- a dictionary mapping label field names to keys to use when
constructing the label dictionaries to pass to the exporter
Note that multiple fields can only be specified when the
exporter used can handle dictionaries of labels. By default,
the first field of compatible type for the exporter is used.
When exporting labeled video datasets, this argument may
contain frame fields prefixed by `"frames."`
* **frame_labels_field** (*None*) –
controls the frame label field(s) to
export. The `"frames."` prefix is optional. Only applicable
to labeled video datasets. Can be any of the following:
- the name of a frame label field to export
- a glob pattern of frame label field(s) to export
- a list or tuple of frame label field(s) to export
- a dictionary mapping frame label field names to keys to use
when constructing the frame label dictionaries to pass to
the exporter
Note that multiple fields can only be specified when the
exporter used can handle dictionaries of frame labels. By
default, the first field of compatible type for the exporter is
used
* **overwrite** (*False*) – whether to delete existing directories before
performing the export (True) or to merge the export with
existing files and directories (False)
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **\*\*kwargs** – optional keyword arguments to pass to the dataset
exporter’s constructor. If you are exporting image patches,
this can also contain keyword arguments for
[`fiftyone.utils.patches.ImagePatchesExtractor`](fiftyone.utils.patches.md#fiftyone.utils.patches.ImagePatchesExtractor)
#### filter_field(field, filter, only_matches=True)
Filters the values of a field or embedded field of each sample in
the 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"
#
view = dataset.filter_field("predictions", F("label") == "cat")
#
# Only include samples whose `numeric_field` value is positive
#
view = dataset.filter_field("numeric_field", F() > 0)
```
* **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 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)
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### filter_keypoints(field, filter=None, labels=None, only_matches=True)
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 [`filter_labels()`](#fiftyone.core.clips.TrajectoriesView.filter_labels) 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
#
view = dataset.filter_keypoints(
"predictions", filter=F("confidence") > 0.9
)
#
# Only include keypoints in the `predictions` field with less than
# four points
#
view = dataset.filter_keypoints(
"predictions", labels=["left eye", "right eye"]
)
```
* **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)
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### filter_labels(field, filter, only_matches=True, trajectories=False)
Filters the [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) field of each
sample in the 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
#
view = dataset.filter_labels("predictions", F("confidence") > 0.8)
#
# Only include classifications in the `predictions` field whose
# `label` is "cat" or "dog"
#
view = dataset.filter_labels(
"predictions", F("label").is_in(["cat", "dog"])
)
```
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
#
view = dataset.filter_labels("predictions", F("confidence") > 0.8)
#
# Only include detections in the `predictions` field whose `label`
# is "cat" or "dog"
#
view = dataset.filter_labels(
"predictions", F("label").is_in(["cat", "dog"])
)
#
# 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]
view = dataset.filter_labels("predictions", bbox_area < 0.2)
```
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
#
view = dataset.filter_labels("predictions", F("filled") == True)
#
# Only include polylines in the `predictions` field whose `label`
# is "lane"
#
view = dataset.filter_labels("predictions", F("label") == "lane")
#
# Only include polylines in the `predictions` field with at least
# 3 vertices
#
num_vertices = F("points").map(F().length()).sum()
view = dataset.filter_labels("predictions", num_vertices >= 3)
```
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"
#
view = dataset.filter_labels("predictions", F("label") == "house")
#
# Only include keypoints in the `predictions` field with less than
# four points
#
view = dataset.filter_labels("predictions", F("points").length() < 4)
```
* **Parameters:**
* **field** – the label field to filter
* **filter** –
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 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 datasets that contain videos and
frame-level label fields whose objects have their `index`
attributes populated
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### first()
Returns the first sample in the collection.
* **Returns:**
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)
#### flatten(stages=None)
Returns a flattened view that contains all samples in the 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
flat_view = grouped_view.flatten(fo.Limit(10))
print(len(flat_view)) # 100
```
* **Parameters:**
**stages** (*None*) – a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage) or list of
[`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage) instances to apply to
each group’s samples while flattening
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### generate_label_schemas(fields=None, scan_samples=True)
Generates label schemas for the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection).
A label schema is defined by a `type` and `component` with respect
to a field. Further settings depend on the `type` and `component`
combination as outlined below.
The `type` value for a field is inferred from the collection’s field
schema. See
[`fiftyone.core.collections.SampleCollection.get_field_schema()`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection.get_field_schema)
Currently supported media types for the collection are `image` and
`3d`. See
[`fiftyone.core.collections.SampleCollection.media_type`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection.media_type)
**Primitives and components**
Supported primitive types are:
> - `bool`: [`fiftyone.core.fields.BooleanField`](fiftyone.core.fields.md#fiftyone.core.fields.BooleanField)
> - `date`: [`fiftyone.core.fields.DateField`](fiftyone.core.fields.md#fiftyone.core.fields.DateField)
> - `datetime`: [`fiftyone.core.fields.DateTimeField`](fiftyone.core.fields.md#fiftyone.core.fields.DateTimeField)
> - `dict`: [`fiftyone.core.fields.DictField`](fiftyone.core.fields.md#fiftyone.core.fields.DictField)
> - `float`: [`fiftyone.core.fields.FloatField`](fiftyone.core.fields.md#fiftyone.core.fields.FloatField)
> - `id`: [`fiftyone.core.fields.ObjectIdField`](fiftyone.core.fields.md#fiftyone.core.fields.ObjectIdField) or
> [`fiftyone.core.fields.UUIDField`](fiftyone.core.fields.md#fiftyone.core.fields.UUIDField)
> - `int`: [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField) or
> [`fiftyone.core.fields.FrameNumberField`](fiftyone.core.fields.md#fiftyone.core.fields.FrameNumberField)
> - `list`: [`fiftyone.core.fields.ListField`](fiftyone.core.fields.md#fiftyone.core.fields.ListField) of
> [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField)
> - `list`: [`fiftyone.core.fields.ListField`](fiftyone.core.fields.md#fiftyone.core.fields.ListField) of
> [`fiftyone.core.fields.FloatField`](fiftyone.core.fields.md#fiftyone.core.fields.FloatField)
> - `list`: [`fiftyone.core.fields.ListField`](fiftyone.core.fields.md#fiftyone.core.fields.ListField) of
> [`fiftyone.core.fields.StringField`](fiftyone.core.fields.md#fiftyone.core.fields.StringField)
> - `str`: [`fiftyone.core.fields.StringField`](fiftyone.core.fields.md#fiftyone.core.fields.StringField)
Supported `bool` components are:
> - `checkbox`
> - `toggle` - the default
`date` and `datetime` only support the `datepicker` component.
`dict` only supports the `json` component.
Supported `float` and `int` components are:
> - `dropdown`
> - `radio`
> - `slider`: the default when `scan_samples` is `True` and
> distinct finite bounds are found that define a `range`
> - `text`: the default when `scan_samples` is `False` or
> distinct finite bounds are not found
Supported `list` and `list` components are:
> - `checkboxes`
> - `dropdown`
> - `text` - the default
Supported `list` components are:
> - `checkboxes`: the default if `<=5` values are scanned
> - `dropdown`: the default if `>5` and `<=1000` values are
> scanned
> - `text`: the default if `0` values or `>1000` values are
> scanned, or `scan_samples` is `False`
Supported `str` type components are:
> - `dropdown`: the default if `>5` and `<=1000` values are
> scanned
> - `radio`: the default if `<=5` values are scanned
> - `text`: the default if `0` values or `>1000` values are
> scanned, or `scan_samples` is `False`
`float` types support a `precision` setting when a `text`
component is configured for the number of digits to allow after the
decimal.
All types support a `read_only` flag. `id` types must be
`read_only`. If a field is `read_only` in the field schema, then
the `read_only` label schema setting must be `True`, e.g.
`created_at` and `last_modified_at` must be read only.
All components support `values` except `json`, `slider`, and
`toggle` excepting `id` restrictions.
`checkboxes` and `dropdown` require the `values` setting.
`slider` requires the `range: [min, max]` setting.
**Labels**
The `label` subfield of all label types are configured via `classes`
and support the same settings as a `str` type. See the example output
below for `detections` fields in the quickstart dataset. If the label
type has a visual representation, that field is handled by the App’s
builtin annotation UI, e.g. `bounding_box` for a `detection`.
Primitive attributes of label types are configured via the
`attributes` list.
When a label is marked as `read_only`, all its attributes inherit the
setting as well.
All [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) types are resolved by this
method except [`fiftyone.core.labels.GeoLocation`](fiftyone.core.labels.md#fiftyone.core.labels.GeoLocation),
[`fiftyone.core.labels.GeoLocations`](fiftyone.core.labels.md#fiftyone.core.labels.GeoLocations),
[`fiftyone.core.labels.TemporalDetection`](fiftyone.core.labels.md#fiftyone.core.labels.TemporalDetection), and
[`fiftyone.core.labels.TemporalDetections`](fiftyone.core.labels.md#fiftyone.core.labels.TemporalDetections) when provided
in the `fields` argument, otherwise only App supported fields are
resolved. For label types supported
by the App for annotation, see
[`fiftyone.core.annotation.utils.get_supported_app_annotation_fields()`](fiftyone.core.annotation.utils.md#fiftyone.core.annotation.utils.get_supported_app_annotation_fields).
All attributes and the label class itself support a `default` setting
that applies when creating a new label.
**Embedded documents**
One level of nesting is supported via `dot.notation` for
`fiftyone.core.fields.EmbeddedDocumentField`` fields for the
default `metadata` field and the
`fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument``
document type. All label and primitive types are supported. See
[here](../user_guide/using_datasets.md#dynamic-attributes) for more details on adding dynamic
attributes.
Example:
```default
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("quickstart")
dataset.compute_metadata()
fo.pprint(dataset.generate_label_schemas(scan_samples=False))
```
Output:
```default
{
"created_at": {
"type": "datetime",
"component": "datepicker",
"read_only": True,
},
"filepath": {"type": "str", "component": "text"},
"ground_truth": {
"attributes": [
{
"name": "attributes",
"type": "dict",
"component": "json",
},
{
"name": "confidence",
"type": "float",
"component": "text",
},
{
"name": "id",
"type": "id",
"component": "text",
"read_only": True,
},
{"name": "index", "type": "int", "component": "text"},
{
"name": "mask_path",
"type": "str",
"component": "text",
},
{
"name": "tags",
"type": "list",
"component": "text",
},
],
"component": "text",
"type": "detections",
},
"id": {"type": "id", "component": "text", "read_only": True},
"last_modified_at": {
"type": "datetime",
"component": "datepicker",
"read_only": True,
},
"metadata.height": {"type": "int", "component": "text"},
"metadata.mime_type": {"type": "str", "component": "text"},
"metadata.num_channels": {"type": "int", "component": "text"},
"metadata.size_bytes": {"type": "int", "component": "text"},
"metadata.width": {"type": "int", "component": "text"},
"predictions": {
"attributes": [
{
"name": "attributes",
"type": "dict",
"component": "json",
},
{
"name": "confidence",
"type": "float",
"component": "text",
},
{
"name": "id",
"type": "id",
"component": "text",
"read_only": True,
},
{"name": "index", "type": "int", "component": "text"},
{
"name": "mask_path",
"type": "str",
"component": "text",
},
{
"name": "tags",
"type": "list",
"component": "text",
},
],
"component": "text",
"type": "detections",
},
"tags": {"type": "list", "component": "text"},
"uniqueness": {"type": "float", "component": "text"},
}
```
* **Parameters:**
* **fields** (*None*) – a field name, `embedded.field.name` or iterable of
such values
* **scan_samples** (*True*) – whether to scan the collection to populate
component settings based on actual field values (ranges,
values, etc). If False, the label schema is generated from
*only* the statically available information in the dataset’s
field schema
* **Raises:**
**ValueError** – if the sample collection or field is not supported
* **Returns:**
a label schemas `dict`, or an individual field’s label schema
`dict` if only one field is provided
#### geo_near(point, location_field=None, min_distance=None, max_distance=None, query=None, create_index=False)
Sorts the samples in the 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
#
view = dataset.geo_near(TIMES_SQUARE, create_index=True)
#
# Sort the samples by their proximity to Times Square, and only
# include samples within 5km
#
view = dataset.geo_near(
TIMES_SQUARE,
max_distance=5000,
create_index=True,
)
#
# 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],
]
]
)
view = dataset.geo_near(
TIMES_SQUARE,
location_field="location",
query=in_manhattan,
create_index=True,
)
```
* **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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### geo_within(boundary, location_field=None, strict=True, create_index=False)
Filters the samples in this collection to only include 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
#
view = dataset.geo_within(MANHATTAN)
```
* **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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### get_annotation_info(anno_key)
Returns information about the annotation run with the given key on
this collection.
* **Parameters:**
**anno_key** – an annotation key
* **Returns:**
a [`fiftyone.core.annotation.AnnotationInfo`](fiftyone.core.annotation.md#fiftyone.core.annotation.AnnotationInfo)
#### get_brain_info(brain_key)
Returns information about the brain method run with the given key on
this collection.
* **Parameters:**
**brain_key** – a brain key
* **Returns:**
a [`fiftyone.core.brain.BrainInfo`](fiftyone.core.brain.md#fiftyone.core.brain.BrainInfo)
#### get_classes(field)
Gets the classes list for the given field, or None if no classes
are available.
Classes are first retrieved from [`classes()`](#fiftyone.core.clips.TrajectoriesView.classes) if they exist,
otherwise from [`default_classes()`](#fiftyone.core.clips.TrajectoriesView.default_classes).
* **Parameters:**
**field** – a field name
* **Returns:**
a list of classes, or None
#### get_dynamic_field_schema(fields=None, recursive=True)
Returns a schema dictionary describing the dynamic fields of the
samples in the collection.
Dynamic fields are embedded document fields with at least one non-None
value that have not been declared on the dataset’s schema.
* **Parameters:**
* **fields** (*None*) – an optional field or iterable of fields for which to
return dynamic fields. By default, all fields are considered
* **recursive** (*True*) – whether to recursively inspect nested lists and
embedded documents
* **Returns:**
a dict mapping field paths to [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
instances or lists of them
#### get_dynamic_frame_field_schema(fields=None, recursive=True)
Returns a schema dictionary describing the dynamic fields of the
frames in the collection.
Dynamic fields are embedded document fields with at least one non-None
value that have not been declared on the dataset’s schema.
* **Parameters:**
* **fields** (*None*) – an optional field or iterable of fields for which to
return dynamic fields. By default, all fields are considered
* **recursive** (*True*) – whether to recursively inspect nested lists and
embedded documents
* **Returns:**
a dict mapping field paths to [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
instances or lists of them, or `None` if the collection does not
contain videos
#### get_dynamic_group(group_value)
Returns a view containing the samples from a dynamic grouped view
with the given group value.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("cifar10", split="test")
view = dataset.take(1000).group_by("ground_truth.label")
group = view.get_dynamic_group("cat")
print(len(group)) # 104
```
* **Parameters:**
**group_value** – the group value
* **Returns:**
a `DatasetView`
#### get_evaluation_info(eval_key)
Returns information about the evaluation with the given key on this
collection.
* **Parameters:**
**eval_key** – an evaluation key
* **Returns:**
an [`fiftyone.core.evaluation.EvaluationInfo`](fiftyone.core.evaluation.md#fiftyone.core.evaluation.EvaluationInfo)
#### get_field(path, ftype=None, embedded_doc_type=None, subfield=None, read_only=None, include_private=False, leaf=False)
Returns the field instance of the provided path, or `None` if one
does not exist.
* **Parameters:**
* **path** – a field path
* **ftype** (*None*) – an optional field type or iterable of types to
enforce. Must be subclass(es) of
[`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
* **embedded_doc_type** (*None*) – an optional embedded document type or
iterable of types to enforce. Must be subclass(es) of
[`fiftyone.core.odm.BaseEmbeddedDocument`](fiftyone.core.odm.md#fiftyone.core.odm.BaseEmbeddedDocument)
* **subfield** (*None*) – an optional subfield type or iterable of subfield
types to enforce. Must be subclass(es) of
[`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
* **read_only** (*None*) – whether to optionally enforce that the field is
read-only (True) or not read-only (False)
* **include_private** (*False*) – whether to include fields that start with
`_` in the returned schema
* **leaf** (*False*) – whether to return the subfield of list fields
* **Returns:**
a [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field) instance or `None`
* **Raises:**
**ValueError** – if the field does not match provided constraints
#### get_field_schema(ftype=None, embedded_doc_type=None, subfield=None, read_only=None, info_keys=None, created_after=None, include_private=False, flat=False, unwind=True, mode=None)
Returns a schema dictionary describing the fields of the samples in
the view.
* **Parameters:**
* **ftype** (*None*) – an optional field type or iterable of types to which
to restrict the returned schema. Must be subclass(es) of
[`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
* **embedded_doc_type** (*None*) – an optional embedded document type or
iterable of types to which to restrict the returned schema.
Must be subclass(es) of
[`fiftyone.core.odm.BaseEmbeddedDocument`](fiftyone.core.odm.md#fiftyone.core.odm.BaseEmbeddedDocument)
* **subfield** (*None*) – an optional subfield type or iterable of subfield
types to which to restrict the returned schema. Must be
subclass(es) of [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
* **read_only** (*None*) – whether to restrict to (True) or exclude (False)
read-only fields. By default, all fields are included
* **info_keys** (*None*) – an optional key or list of keys that must be in
the field’s `info` dict
* **created_after** (*None*) – an optional `datetime` specifying a minimum
creation date
* **include_private** (*False*) – whether to include fields that start with
`_` in the returned schema
* **flat** (*False*) – whether to return a flattened schema where all
embedded document fields are included as top-level keys
* **unwind** (*True*) – whether to traverse into list fields. Only
applicable when `flat=True`
* **mode** (*None*) – whether to apply the above constraints before and/or
after flattening the schema. Only applicable when `flat=True`.
Supported values are `("before", "after", "both")`. The
default is `"after"`
* **Returns:**
a dict mapping field names to [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
instances
#### get_frame_field_schema(ftype=None, embedded_doc_type=None, subfield=None, read_only=None, info_keys=None, created_after=None, include_private=False, flat=False, unwind=True, mode=None)
Returns a schema dictionary describing the fields of the frames of
the samples in the view.
Only applicable for views that contain videos.
* **Parameters:**
* **ftype** (*None*) – an optional field type or iterable of types to which
to restrict the returned schema. Must be subclass(es) of
[`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
* **embedded_doc_type** (*None*) – an optional embedded document type or
iterable of types to which to restrict the returned schema.
Must be subclass(es) of
[`fiftyone.core.odm.BaseEmbeddedDocument`](fiftyone.core.odm.md#fiftyone.core.odm.BaseEmbeddedDocument)
* **subfield** (*None*) – an optional subfield type or iterable of subfield
types to which to restrict the returned schema. Must be
subclass(es) of [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
* **read_only** (*None*) – whether to restrict to (True) or exclude (False)
read-only fields. By default, all fields are included
* **info_keys** (*None*) – an optional key or list of keys that must be in
the field’s `info` dict
* **created_after** (*None*) – an optional `datetime` specifying a minimum
creation date
* **include_private** (*False*) – whether to include fields that start with
`_` in the returned schema
* **flat** (*False*) – whether to return a flattened schema where all
embedded document fields are included as top-level keys
* **unwind** (*True*) – whether to traverse into list fields. Only
applicable when `flat=True`
* **mode** (*None*) – whether to apply the above constraints before and/or
after flattening the schema. Only applicable when `flat=True`.
Supported values are `("before", "after", "both")`. The
default is `"after"`
* **Returns:**
a dict mapping field names to [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
instances, or `None` if the view does not contain videos
#### get_group(group_id, group_slices=None)
Returns a dict containing the samples for the given group ID.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("quickstart-groups")
view = dataset.select_fields()
group_id = view.take(1).first().group.id
group = view.get_group(group_id)
print(group.keys())
# ['left', 'right', 'pcd']
```
* **Parameters:**
* **group_id** – a group ID
* **group_slices** (*None*) – an optional subset of group slices to load
* **Returns:**
a dict mapping group names to
[`fiftyone.core.sample.SampleView`](fiftyone.core.sample.md#fiftyone.core.sample.SampleView) instances
* **Raises:**
**KeyError** – if the group ID is not found
#### get_index_information(include_stats=False, \_keep_index_names=False)
Returns a dictionary of information about the indexes on this
collection.
See [`pymongo.collection.Collection.index_information()`](https://pymongo.readthedocs.io/en/stable/api/pymongo/collection.html#pymongo.collection.Collection.index_information) for
details on the structure of this dictionary.
* **Parameters:**
**include_stats** (*False*) – whether to include the size, usage, and
build status of each index
* **Returns:**
a dict mapping index names to info dicts
#### get_mask_targets(field)
Gets the mask targets for the given field, or None if no mask
targets are available.
Mask targets are first retrieved from [`mask_targets()`](#fiftyone.core.clips.TrajectoriesView.mask_targets) if they
exist, otherwise from [`default_mask_targets()`](#fiftyone.core.clips.TrajectoriesView.default_mask_targets).
* **Parameters:**
**field** – a field name
* **Returns:**
a list of classes, or None
#### get_run_info(run_key)
Returns information about the run with the given key on this
collection.
* **Parameters:**
**run_key** – a run key
* **Returns:**
a [`fiftyone.core.runs.RunInfo`](fiftyone.core.runs.md#fiftyone.core.runs.RunInfo)
#### get_skeleton(field)
Gets the keypoint skeleton for the given field, or None if no
skeleton is available.
Skeletons are first retrieved from [`skeletons()`](#fiftyone.core.clips.TrajectoriesView.skeletons) if they exist,
otherwise from [`default_skeleton()`](#fiftyone.core.clips.TrajectoriesView.default_skeleton).
* **Parameters:**
**field** – a field name
* **Returns:**
a list of classes, or None
#### group_by(field_or_expr, order_by=None, reverse=False, flat=False, match_expr=None, sort_expr=None, create_index=False, order_by_key=None)
Creates a view that groups the samples in the 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
#
view = dataset.take(1000).group_by("ground_truth.label")
for group in view.iter_dynamic_groups():
group_value = group.first().ground_truth.label
print("%s: %d" % (group_value, len(group)))
#
# Variation of above operation that arranges the groups in
# decreasing order of size and immediately flattens them
#
from itertools import groupby
view = dataset.take(1000).group_by(
"ground_truth.label",
flat=True,
sort_expr=F().length(),
reverse=True,
)
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 both to `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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* group_field
The group field of the view, or None if the view is not grouped.
#### *property* group_media_types
A dict mapping group slices to media types, or None if the view is
not grouped.
#### *property* group_slice
The current group slice of the view, or None if the view is not
grouped.
#### *property* group_slices
The list of group slices of the view, or None if the view is not
grouped.
#### has_annotation_run(anno_key)
Whether this collection has an annotation run with the given key.
* **Parameters:**
**anno_key** – an annotation key
* **Returns:**
True/False
#### *property* has_annotation_runs
Whether this collection has any annotation runs.
#### has_brain_run(brain_key)
Whether this collection has a brain method run with the given key.
* **Parameters:**
**brain_key** – a brain key
* **Returns:**
True/False
#### *property* has_brain_runs
Whether this collection has any brain runs.
#### has_classes(field)
Determines whether this collection has a classes list for the given
field.
Classes may be defined either in [`classes()`](#fiftyone.core.clips.TrajectoriesView.classes) or
[`default_classes()`](#fiftyone.core.clips.TrajectoriesView.default_classes).
* **Parameters:**
**field** – a field name
* **Returns:**
True/False
#### has_evaluation(eval_key)
Whether this collection has an evaluation with the given key.
* **Parameters:**
**eval_key** – an evaluation key
* **Returns:**
True/False
#### *property* has_evaluations
Whether this collection has any evaluation results.
#### has_field(path)
Determines whether the collection has a field with the given name.
* **Parameters:**
**path** – the field name or `embedded.field.name`
* **Returns:**
True/False
#### has_frame_field(path)
Determines whether the collection has a frame-level field with the
given name.
* **Parameters:**
**path** – the field name or `embedded.field.name`
* **Returns:**
True/False
#### has_mask_targets(field)
Determines whether this collection has mask targets for the given
field.
Mask targets may be defined either in [`mask_targets()`](#fiftyone.core.clips.TrajectoriesView.mask_targets) or
[`default_mask_targets()`](#fiftyone.core.clips.TrajectoriesView.default_mask_targets).
* **Parameters:**
**field** – a field name
* **Returns:**
True/False
#### has_run(run_key)
Whether this collection has a run with the given key.
* **Parameters:**
**run_key** – a run key
* **Returns:**
True/False
#### *property* has_runs
Whether this collection has any runs.
#### has_sample_field(path)
Determines whether the collection has a sample field with the given
name.
* **Parameters:**
**path** – the field name or `embedded.field.name`
* **Returns:**
True/False
#### has_skeleton(field)
Determines whether this collection has a keypoint skeleton for the
given field.
Keypoint skeletons may be defined either in [`skeletons()`](#fiftyone.core.clips.TrajectoriesView.skeletons) or
[`default_skeleton()`](#fiftyone.core.clips.TrajectoriesView.default_skeleton).
* **Parameters:**
**field** – a field name
* **Returns:**
True/False
#### head(num_samples=3)
Returns a list of the first few samples in the collection.
If fewer than `num_samples` samples are in the collection, only
the available samples are returned.
* **Parameters:**
**num_samples** (*3*) – the number of samples
* **Returns:**
a list of [`fiftyone.core.sample.Sample`](fiftyone.core.sample.md#fiftyone.core.sample.Sample) objects
#### histogram_values(field_or_expr, expr=None, bins=None, range=None, auto=False)
Computes a histogram of the field values in the collection.
This aggregation is typically applied to *numeric* field types (or
lists of such types):
- [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField)
- [`fiftyone.core.fields.FloatField`](fiftyone.core.fields.md#fiftyone.core.fields.FloatField)
Examples:
```default
import numpy as np
import matplotlib.pyplot as plt
import fiftyone as fo
from fiftyone import ViewField as F
samples = []
for idx in range(100):
samples.append(
fo.Sample(
filepath="/path/to/image%d.png" % idx,
numeric_field=np.random.randn(),
numeric_list_field=list(np.random.randn(10)),
)
)
dataset = fo.Dataset()
dataset.add_samples(samples)
def plot_hist(counts, edges):
counts = np.asarray(counts)
edges = np.asarray(edges)
left_edges = edges[:-1]
widths = edges[1:] - edges[:-1]
plt.bar(left_edges, counts, width=widths, align="edge")
#
# Compute a histogram of a numeric field
#
counts, edges, other = dataset.histogram_values(
"numeric_field", bins=50, range=(-4, 4)
)
plot_hist(counts, edges)
plt.show(block=False)
#
# Compute the histogram of a numeric list field
#
counts, edges, other = dataset.histogram_values(
"numeric_list_field", bins=50
)
plot_hist(counts, edges)
plt.show(block=False)
#
# Compute the histogram of a transformation of a numeric field
#
counts, edges, other = dataset.histogram_values(
2 * (F("numeric_field") + 1), bins=50
)
plot_hist(counts, edges)
plt.show(block=False)
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate. This can also
be a list or tuple of such arguments, in which case a tuple of
corresponding aggregation results (each receiving the same
additional keyword arguments, if any) will be returned
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **bins** (*None*) – can be either an integer number of bins to generate or
a monotonically increasing sequence specifying the bin edges to
use. By default, 10 bins are created. If `bins` is an integer
and no `range` is specified, bin edges are automatically
distributed in an attempt to evenly distribute the counts in
each bin
* **range** (*None*) – a `(lower, upper)` tuple specifying a range in
which to generate equal-width bins. Only applicable when
`bins` is an integer
* **auto** (*False*) – whether to automatically choose bin edges in an
attempt to evenly distribute the counts in each bin. If this
option is chosen, `bins` will only be used if it is an
integer, and the `range` parameter is ignored
* **Returns:**
a tuple of
- counts: a list of counts in each bin
- edges: an increasing list of bin edges of length
`len(counts) + 1`. Note that each bin is treated as having an
inclusive lower boundary and exclusive upper boundary,
`[lower, upper)`, including the rightmost bin
- other: the number of items outside the bins
#### *property* info
The info dict of the underlying dataset.
See [`fiftyone.core.dataset.Dataset.info()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.info) for more information.
#### init_run(\*\*kwargs)
Initializes a config instance for a new run.
* **Parameters:**
**\*\*kwargs** – JSON serializable config parameters
* **Returns:**
a [`fiftyone.core.runs.RunConfig`](fiftyone.core.runs.md#fiftyone.core.runs.RunConfig)
#### init_run_results(run_key, \*\*kwargs)
Initializes a results instance for the run with the given key.
* **Parameters:**
* **run_key** – a run key
* **\*\*kwargs** – JSON serializable data
* **Returns:**
a [`fiftyone.core.runs.RunResults`](fiftyone.core.runs.md#fiftyone.core.runs.RunResults)
#### iter_dynamic_groups(progress=False)
Returns an iterator over the dynamic groups in the view.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("cifar10", split="test")
view = dataset.take(1000).group_by("ground_truth.label")
for group in view.iter_dynamic_groups():
group_value = group.first().ground_truth.label
print("%s: %d" % (group_value, len(group)))
```
* **Parameters:**
**progress** (*False*) – whether to render a progress bar (True/False),
use the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **Returns:**
an iterator that emits `DatasetView` instances, one per
group
#### iter_groups(group_slices=None, progress=False, autosave=False, batch_size=None, batching_strategy=None)
Returns an iterator over the groups in the view.
Examples:
```default
import random as r
import string as s
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("quickstart-groups")
view = dataset.select_fields()
def make_label():
return "".join(r.choice(s.ascii_letters) for i in range(10))
# No save context
for group in view.iter_groups(progress=True):
for sample in group.values():
sample["test"] = make_label()
sample.save()
# Save using default batching strategy
for group in view.iter_groups(progress=True, autosave=True):
for sample in group.values():
sample["test"] = make_label()
# Save in batches of 10
for group in view.iter_groups(
progress=True, autosave=True, batch_size=10
):
for sample in group.values():
sample["test"] = make_label()
# Save every 0.5 seconds
for group in view.iter_groups(
progress=True, autosave=True, batch_size=0.5
):
for sample in group.values():
sample["test"] = make_label()
```
* **Parameters:**
* **group_slices** (*None*) – an optional subset of group slices to load
* **progress** (*False*) – whether to render a progress bar (True/False),
use the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **autosave** (*False*) – whether to automatically save changes to samples
emitted by this iterator
* **batch_size** (*None*) – the batch size to use when autosaving samples.
If a `batching_strategy` is provided, this parameter
configures the strategy as described below. If no
`batching_strategy` is provided, this can either be an
integer specifying the number of samples to save in a batch
(in which case `batching_strategy` is implicitly set to
`"static"`) or a float number of seconds between batched
saves (in which case `batching_strategy` is implicitly set to
`"latency"`)
* **batching_strategy** (*None*) –
the batching strategy to use for each
save operation when autosaving samples. Supported values are:
- `"static"`: a fixed sample batch size for each save
- `"size"`: a target batch size, in bytes, for each save
- `"latency"`: a target latency, in seconds, between saves
By default, `fo.config.default_batcher` is used
* **Returns:**
an iterator that emits dicts mapping slice names to
[`fiftyone.core.sample.SampleView`](fiftyone.core.sample.md#fiftyone.core.sample.SampleView) instances, one per group
#### iter_samples(progress=False, autosave=False, batch_size=None, batching_strategy=None)
Returns an iterator over the samples in the view.
Examples:
```default
import random as r
import string as s
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("cifar10", split="test")
view = dataset.shuffle().limit(5000)
def make_label():
return "".join(r.choice(s.ascii_letters) for i in range(10))
# No save context
for sample in view.iter_samples(progress=True):
sample.ground_truth.label = make_label()
sample.save()
# Save using default batching strategy
for sample in view.iter_samples(progress=True, autosave=True):
sample.ground_truth.label = make_label()
# Save in batches of 10
for sample in view.iter_samples(
progress=True, autosave=True, batch_size=10
):
sample.ground_truth.label = make_label()
# Save every 0.5 seconds
for sample in view.iter_samples(
progress=True, autosave=True, batch_size=0.5
):
sample.ground_truth.label = make_label()
```
* **Parameters:**
* **progress** (*False*) – whether to render a progress bar (True/False),
use the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **autosave** (*False*) – whether to automatically save changes to samples
emitted by this iterator
* **batch_size** (*None*) – the batch size to use when autosaving samples.
If a `batching_strategy` is provided, this parameter
configures the strategy as described below. If no
`batching_strategy` is provided, this can either be an
integer specifying the number of samples to save in a batch
(in which case `batching_strategy` is implicitly set to
`"static"`) or a float number of seconds between batched
saves (in which case `batching_strategy` is implicitly set to
`"latency"`)
* **batching_strategy** (*None*) –
the batching strategy to use for each
save operation when autosaving samples. Supported values are:
- `"static"`: a fixed sample batch size for each save
- `"size"`: a target batch size, in bytes, for each save
- `"latency"`: a target latency, in seconds, between saves
By default, `fo.config.default_batcher` is used
* **Returns:**
an iterator over [`fiftyone.core.sample.SampleView`](fiftyone.core.sample.md#fiftyone.core.sample.SampleView) instances
#### keep()
Deletes all clips that are **not** in this view from the underlying
dataset.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### keep_fields()
Deletes any frame fields that have been excluded in this view from
the frames of the underlying dataset.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### keep_frames()
For each sample in the view, deletes all frames labels that are
**not** in the view from the underlying dataset.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### last()
Returns the last sample in the collection.
* **Returns:**
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)
#### limit(limit)
Returns 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
#
view = dataset.limit(2)
```
* **Parameters:**
**limit** – the maximum number of samples to return. If a non-positive
number is provided, an empty view is returned
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### limit_labels(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 the 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
#
view = dataset.limit_labels("predictions", 1)
```
* **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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *classmethod* list_aggregations()
Returns a list of all available methods on this collection that
apply [`fiftyone.core.aggregations.Aggregation`](fiftyone.core.aggregations.md#fiftyone.core.aggregations.Aggregation) operations to
this collection.
* **Returns:**
a list of `SampleCollection` method names
#### list_annotation_runs(type=None, method=None, \*\*kwargs)
Returns a list of annotation keys on this collection.
* **Parameters:**
* **type** (*None*) –
a specific annotation run type to match, which can be:
- a string
`fiftyone.core.annotations.AnnotationMethodConfig.type`
- a `fiftyone.core.annotations.AnnotationMethod` class
or its fully-qualified class name string
* **method** (*None*) – a specific
`fiftyone.core.annotations.AnnotationMethodConfig.method`
string to match
* **\*\*kwargs** – optional config parameters to match
* **Returns:**
a list of annotation keys
#### list_brain_runs(type=None, method=None, \*\*kwargs)
Returns a list of brain keys on this collection.
* **Parameters:**
* **type** (*None*) –
a specific brain run type to match, which can be:
- a string [`fiftyone.core.brain.BrainMethodConfig.type`](fiftyone.core.brain.md#fiftyone.core.brain.BrainMethodConfig.type)
- a [`fiftyone.core.brain.BrainMethod`](fiftyone.core.brain.md#fiftyone.core.brain.BrainMethod) class or its
fully-qualified class name string
* **method** (*None*) – a specific
[`fiftyone.core.brain.BrainMethodConfig.method`](fiftyone.core.brain.md#fiftyone.core.brain.BrainMethodConfig.method) string to
match
* **\*\*kwargs** – optional config parameters to match
* **Returns:**
a list of brain keys
#### list_evaluations(type=None, method=None, \*\*kwargs)
Returns a list of evaluation keys on this collection.
* **Parameters:**
* **type** (*None*) –
a specific evaluation type to match, which can be:
- a string
`fiftyone.core.evaluations.EvaluationMethodConfig.type`
- a `fiftyone.core.evaluations.EvaluationMethod` class
or its fully-qualified class name string
* **method** (*None*) – a specific
`fiftyone.core.evaluations.EvaluationMethodConfig.method`
string to match
* **\*\*kwargs** – optional config parameters to match
* **Returns:**
a list of evaluation keys
#### list_indexes()
Returns the list of index names on this collection.
Single-field indexes are referenced by their field name, while compound
indexes are referenced by more complicated strings. See
[`pymongo.collection.Collection.index_information()`](https://pymongo.readthedocs.io/en/stable/api/pymongo/collection.html#pymongo.collection.Collection.index_information) for
details on the compound format.
* **Returns:**
the list of index names
#### list_runs(\*\*kwargs)
Returns a list of run keys on this collection.
* **Parameters:**
**\*\*kwargs** – optional config parameters to match
* **Returns:**
a list of run keys
#### list_schema(field_or_expr, expr=None)
Extracts the value type(s) in a specified list field across all
samples in the collection.
Examples:
```default
from datetime import datetime
import fiftyone as fo
dataset = fo.Dataset()
sample1 = fo.Sample(
filepath="image1.png",
ground_truth=fo.Classification(
label="cat",
info=[
fo.DynamicEmbeddedDocument(
task="initial_annotation",
author="Alice",
timestamp=datetime(1970, 1, 1),
notes=["foo", "bar"],
),
fo.DynamicEmbeddedDocument(
task="editing_pass",
author="Bob",
timestamp=datetime.utcnow(),
),
],
),
)
sample2 = fo.Sample(
filepath="image2.png",
ground_truth=fo.Classification(
label="dog",
info=[
fo.DynamicEmbeddedDocument(
task="initial_annotation",
author="Bob",
timestamp=datetime(2018, 10, 18),
notes=["spam", "eggs"],
),
],
),
)
dataset.add_samples([sample1, sample2])
# Determine that `ground_truth.info` contains embedded documents
print(dataset.list_schema("ground_truth.info"))
# fo.EmbeddedDocumentField
# Determine the fields of the embedded documents in the list
print(dataset.schema("ground_truth.info[]"))
# {'task': StringField, ..., 'notes': ListField}
# Determine the type of the values in the nested `notes` list field
# Since `ground_truth.info` is not yet declared on the dataset's
# schema, we must manually include `[]` to unwind the info lists
print(dataset.list_schema("ground_truth.info[].notes"))
# fo.StringField
# Declare the `ground_truth.info` field
dataset.add_sample_field(
"ground_truth.info",
fo.ListField,
subfield=fo.EmbeddedDocumentField,
embedded_doc_type=fo.DynamicEmbeddedDocument,
)
# Now we can inspect the nested `notes` field without unwinding
print(dataset.list_schema("ground_truth.info.notes"))
# fo.StringField
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **Returns:**
a [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field) or list of
[`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field) instances describing the value
type(s) in the list
#### *classmethod* list_view_stages()
Returns a list of all available methods on this collection that
apply [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage) operations to this
collection.
* **Returns:**
a list of `SampleCollection` method names
#### load_annotation_results(anno_key, cache=True, \*\*kwargs)
Loads the results for the annotation run with the given key on this
collection.
The [`fiftyone.utils.annotations.AnnotationResults`](fiftyone.utils.annotations.md#fiftyone.utils.annotations.AnnotationResults) object
returned by this method will provide a variety of backend-specific
methods allowing you to perform actions such as checking the status and
deleting this run from the annotation backend.
Use [`load_annotations()`](#fiftyone.core.clips.TrajectoriesView.load_annotations) to load the labels from an annotation
run onto your FiftyOne dataset.
* **Parameters:**
* **anno_key** – an annotation key
* **cache** (*True*) – whether to cache the results on the collection
* **\*\*kwargs** – keyword arguments for run’s
[`fiftyone.core.annotation.AnnotationMethodConfig.load_credentials()`](fiftyone.core.annotation.md#fiftyone.core.annotation.AnnotationMethodConfig.load_credentials)
method
* **Returns:**
a [`fiftyone.utils.annotations.AnnotationResults`](fiftyone.utils.annotations.md#fiftyone.utils.annotations.AnnotationResults)
#### load_annotation_view(anno_key, select_fields=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) on which the
specified annotation run was performed on this collection.
* **Parameters:**
* **anno_key** – an annotation key
* **select_fields** (*False*) – whether to exclude fields involved in other
annotation runs
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### load_annotations(anno_key, dest_field=None, unexpected='prompt', cleanup=False, progress=None, \*\*kwargs)
Downloads the labels from the given annotation run from the
annotation backend and merges them into this collection.
See [this page](../integrations/annotation.md#loading-annotations) for more information
about using this method to import annotations that you have scheduled
by calling [`annotate()`](#fiftyone.core.clips.TrajectoriesView.annotate).
* **Parameters:**
* **anno_key** – an annotation key
* **dest_field** (*None*) – an optional name of a new destination field
into which to load the annotations, or a dict mapping field names
in the run’s label schema to new destination field names
* **unexpected** ( *"prompt"*) –
how to deal with any unexpected labels that
don’t match the run’s label schema when importing. The
supported values are:
- `"prompt"`: present an interactive prompt to
direct/discard unexpected labels
- `"ignore"`: automatically ignore any unexpected labels
- `"keep"`: automatically keep all unexpected labels in a
field whose name matches the label type
- `"return"`: return a dict containing all unexpected
labels, or `None` if there aren’t any
* **cleanup** (*False*) – whether to delete any information regarding this
run from the annotation backend after loading the annotations
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
* **\*\*kwargs** – keyword arguments for the run’s
[`fiftyone.core.annotation.AnnotationMethodConfig.load_credentials()`](fiftyone.core.annotation.md#fiftyone.core.annotation.AnnotationMethodConfig.load_credentials)
method
* **Returns:**
`None`, unless `unexpected=="return"` and unexpected labels are
found, in which case a dict containing the extra labels is returned
#### load_brain_results(brain_key, cache=True, load_view=True, \*\*kwargs)
Loads the results for the brain method run with the given key on
this collection.
* **Parameters:**
* **brain_key** – a brain key
* **cache** (*True*) – whether to cache the results on the collection
* **load_view** (*True*) – whether to load the view on which the results
were computed (True) or the full dataset (False)
* **\*\*kwargs** – keyword arguments for the run’s
[`fiftyone.core.brain.BrainMethodConfig.load_credentials()`](fiftyone.core.brain.md#fiftyone.core.brain.BrainMethodConfig.load_credentials)
method
* **Returns:**
a [`fiftyone.core.brain.BrainResults`](fiftyone.core.brain.md#fiftyone.core.brain.BrainResults)
#### load_brain_view(brain_key, select_fields=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) on which the
specified brain method run was performed on this collection.
* **Parameters:**
* **brain_key** – a brain key
* **select_fields** (*False*) – whether to exclude fields involved in other
brain method runs
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### load_evaluation_results(eval_key, cache=True, \*\*kwargs)
Loads the results for the evaluation with the given key on this
collection.
* **Parameters:**
* **eval_key** – an evaluation key
* **cache** (*True*) – whether to cache the results on the collection
* **\*\*kwargs** – keyword arguments for the run’s
[`fiftyone.core.evaluation.EvaluationMethodConfig.load_credentials()`](fiftyone.core.evaluation.md#fiftyone.core.evaluation.EvaluationMethodConfig.load_credentials)
method
* **Returns:**
a [`fiftyone.core.evaluation.EvaluationResults`](fiftyone.core.evaluation.md#fiftyone.core.evaluation.EvaluationResults)
#### load_evaluation_view(eval_key, select_fields=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) on which the
specified evaluation was performed on this collection.
* **Parameters:**
* **eval_key** – an evaluation key
* **select_fields** (*False*) – whether to exclude fields involved in other
evaluations
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### load_run_results(run_key, cache=True, load_view=True, \*\*kwargs)
Loads the results for the run with the given key on this collection.
* **Parameters:**
* **run_key** – a run key
* **cache** (*True*) – whether to cache the results on the collection
* **load_view** (*True*) – whether to load the view on which the results
were computed (True) or the full dataset (False)
* **\*\*kwargs** – keyword arguments for the run’s
[`fiftyone.core.runs.RunConfig.load_credentials()`](fiftyone.core.runs.md#fiftyone.core.runs.RunConfig.load_credentials) method
* **Returns:**
a [`fiftyone.core.runs.RunResults`](fiftyone.core.runs.md#fiftyone.core.runs.RunResults)
#### load_run_view(run_key, select_fields=False)
Loads the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) on which the
specified run was performed on this collection.
* **Parameters:**
* **run_key** – a run key
* **select_fields** (*False*) – whether to exclude fields involved in other
runs
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### make_unique_field_name(root='')
Makes a unique field name with the given root name for the
collection.
* **Parameters:**
**root** – an optional root for the output field name
* **Returns:**
the field name
#### map_labels(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 the 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"
#
view = dataset.map_labels("weather", {"partly cloudy": "cloudy"})
#
# Map "rabbit" and "squirrel" predictions to "other"
#
view = dataset.map_labels(
"predictions", {"rabbit": "other", "squirrel": "other"}
)
```
* **Parameters:**
* **field** – the labels field to map
* **map** – a dict mapping label values to new label values
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### map_samples(map_fcn, save=False, skip_failures=False, parallelize_method=None, num_workers=None, batch_method=None, batch_size=None, progress=None)
Applies the given function to each sample in the collection and
returns the results as a generator.
By default, a multiprocessing pool is used to parallelize the work,
unless this method is called in a daemon process (subprocess), in which
case no workers are used.
This function effectively performs the following map operation with the
outer loop in parallel:
```default
for batch_view in fou.iter_slices(sample_collection, batch_size):
for sample in batch_view.iter_samples(autosave=save):
sample_output = map_fcn(sample)
yield sample.id, sample_output
```
Example:
```default
from collections import Counter
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("cifar10", split="train")
view = dataset.select_fields("ground_truth")
def map_fcn(sample):
return sample.ground_truth.label.upper()
counter = Counter()
for _, label in view.map_samples(map_fcn):
counter[label] += 1
print(dict(counter))
```
* **Parameters:**
* **map_fcn** – a function to apply to each sample in the collection
* **save** (*False*) – whether to save any sample edits applied by
`map_fcn`
* **skip_failures** (*False*) – whether to gracefully continue without
raising an error if the update function raises an exception for
a sample
* **parallelize_method** (*None*) – the parallelization method to use.
Supported values are `{"process", "thread"}`. The default is
`fiftyone.config.default_parallelization_method`
* **num_workers** (*None*) – the number of workers to use. When using
process parallelism, this defaults to
`fiftyone.config.default_process_pool_workers` if the value
is set, else
[`fiftyone.core.utils.recommend_process_pool_workers()`](fiftyone.core.utils.md#fiftyone.core.utils.recommend_process_pool_workers)
workers are used. If this value is <= 1, all work is done in
the main process
* **batch_method** (*None*) – whether to use IDs (`"id"`) or slices
(`"slice"`) to assign samples to workers
* **batch_size** (*None*) – an optional number of samples to distribute to
each worker at a time. By default, samples are evenly
distributed to workers with one batch per worker
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead, or
“workers” to render per-worker progress bars
* **Returns:**
a generator that emits `(sample_id, map_output)` tuples
#### map_values(field, map)
Maps the values in the given field to new values for each sample in
the 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
#
view = dataset.map_values("str_field", mapping)
print(view.count_values("str_field"))
# {"animal": 200}
view = dataset.map_values("list_field", mapping)
print(view.count_values("list_field"))
# {"animal": 200}
#
# Map values in nested fields
#
view = dataset.map_values("ground_truth.detections.label", mapping)
print(view.count_values("ground_truth.detections.label"))
# {"animal": 183, ...}
view = dataset.map_values("ground_truth.detections.tags", mapping)
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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* mask_targets
The mask targets of the underlying dataset.
See [`fiftyone.core.dataset.Dataset.mask_targets()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.mask_targets) for more
information.
#### match(filter)
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"
#
view = dataset.match(F("filepath").ends_with(".jpg"))
#
# Only include samples whose `weather` field is "sunny"
#
view = dataset.match(F("weather.label") == "sunny")
#
# Only include samples with at least 2 objects in their
# `predictions` field
#
view = dataset.match(F("predictions.detections").length() >= 2)
#
# 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)
view = dataset.match(small_boxes.length() > 0)
```
* **Parameters:**
**filter** –
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 describing the filter to apply
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### match_frames(filter, omit_empty=True)
Filters the frames in the 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()
view = dataset.match_frames(num_objects > 10)
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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### match_labels(labels=None, ids=None, instance_ids=None, tags=None, filter=None, fields=None, bool=None)
Selects the samples from the collection that contain (or do not
contain) at least one label that matches the specified criteria.
Note that, unlike [`select_labels()`](#fiftyone.core.clips.TrajectoriesView.select_labels) and [`filter_labels()`](#fiftyone.core.clips.TrajectoriesView.filter_labels), 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...
view = dataset.match_labels(labels=session.selected_labels)
#
# 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,
]
view = dataset.match_labels(ids=ids)
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
view = dataset.match_labels(tags="test")
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
view = dataset.match_labels(filter=filter, fields="predictions")
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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### match_tags(tags, bool=None, all=False)
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
#
view = dataset.match_tags("test")
#
# Only include samples that do not have the "test" tag
#
view = dataset.match_tags("test", bool=False)
#
# Only include samples that have the "test" or "train" tags
#
view = dataset.match_tags(["test", "train"])
#
# Only include samples that have the "test" and "train" tags
#
view = dataset.match_tags(["test", "train"], all=True)
#
# Only include samples that do not have the "test" or "train" tags
#
view = dataset.match_tags(["test", "train"], bool=False)
#
# Only include samples that do not have the "test" and "train" tags
#
view = dataset.match_tags(["test", "train"], bool=False, all=True)
```
* **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 (False) of the given tags
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### max(field_or_expr, expr=None, safe=False)
Computes the maximum of a numeric field of the collection.
`None`-valued fields are ignored.
This aggregation is typically applied to *numeric* or *date* field
types (or lists of such types):
- [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField)
- [`fiftyone.core.fields.FloatField`](fiftyone.core.fields.md#fiftyone.core.fields.FloatField)
- [`fiftyone.core.fields.DateField`](fiftyone.core.fields.md#fiftyone.core.fields.DateField)
- [`fiftyone.core.fields.DateTimeField`](fiftyone.core.fields.md#fiftyone.core.fields.DateTimeField)
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",
numeric_field=1.0,
numeric_list_field=[1, 2, 3],
),
fo.Sample(
filepath="/path/to/image2.png",
numeric_field=4.0,
numeric_list_field=[1, 2],
),
fo.Sample(
filepath="/path/to/image3.png",
numeric_field=None,
numeric_list_field=None,
),
]
)
#
# Compute the maximum of a numeric field
#
max = dataset.max("numeric_field")
print(max) # the max
#
# Compute the maximum of a numeric list field
#
max = dataset.max("numeric_list_field")
print(max) # the max
#
# Compute the maximum of a transformation of a numeric field
#
max = dataset.max(2 * (F("numeric_field") + 1))
print(max) # the max
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate. This can also
be a list or tuple of such arguments, in which case a tuple of
corresponding aggregation results (each receiving the same
additional keyword arguments, if any) will be returned
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **safe** (*False*) – whether to ignore nan/inf values when dealing with
floating point values
* **Returns:**
the maximum value
#### mean(field_or_expr, expr=None, safe=False)
Computes the arithmetic mean of the field values of the collection.
`None`-valued fields are ignored.
This aggregation is typically applied to *numeric* field types (or
lists of such types):
- [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField)
- [`fiftyone.core.fields.FloatField`](fiftyone.core.fields.md#fiftyone.core.fields.FloatField)
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",
numeric_field=1.0,
numeric_list_field=[1, 2, 3],
),
fo.Sample(
filepath="/path/to/image2.png",
numeric_field=4.0,
numeric_list_field=[1, 2],
),
fo.Sample(
filepath="/path/to/image3.png",
numeric_field=None,
numeric_list_field=None,
),
]
)
#
# Compute the mean of a numeric field
#
mean = dataset.mean("numeric_field")
print(mean) # the mean
#
# Compute the mean of a numeric list field
#
mean = dataset.mean("numeric_list_field")
print(mean) # the mean
#
# Compute the mean of a transformation of a numeric field
#
mean = dataset.mean(2 * (F("numeric_field") + 1))
print(mean) # the mean
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate. This can also
be a list or tuple of such arguments, in which case a tuple of
corresponding aggregation results (each receiving the same
additional keyword arguments, if any) will be returned
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **safe** (*False*) – whether to ignore nan/inf values when dealing with
floating point values
* **Returns:**
the mean
#### merge_labels(in_field, out_field)
Merges the labels from the given input field into the given output
field of the collection.
If this collection is a dataset, the input field is deleted after the
merge.
If this collection is a view, the input field will still exist on the
underlying dataset but will only contain the labels not present in this
view.
* **Parameters:**
* **in_field** – the name of the input label field
* **out_field** – the name of the output label field, which will be
created if necessary
#### min(field_or_expr, expr=None, safe=False)
Computes the minimum of a numeric field of the collection.
`None`-valued fields are ignored.
This aggregation is typically applied to *numeric* or *date* field
types (or lists of such types):
- [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField)
- [`fiftyone.core.fields.FloatField`](fiftyone.core.fields.md#fiftyone.core.fields.FloatField)
- [`fiftyone.core.fields.DateField`](fiftyone.core.fields.md#fiftyone.core.fields.DateField)
- [`fiftyone.core.fields.DateTimeField`](fiftyone.core.fields.md#fiftyone.core.fields.DateTimeField)
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",
numeric_field=1.0,
numeric_list_field=[1, 2, 3],
),
fo.Sample(
filepath="/path/to/image2.png",
numeric_field=4.0,
numeric_list_field=[1, 2],
),
fo.Sample(
filepath="/path/to/image3.png",
numeric_field=None,
numeric_list_field=None,
),
]
)
#
# Compute the minimum of a numeric field
#
min = dataset.min("numeric_field")
print(min) # the min
#
# Compute the minimum of a numeric list field
#
min = dataset.min("numeric_list_field")
print(min) # the min
#
# Compute the minimum of a transformation of a numeric field
#
min = dataset.min(2 * (F("numeric_field") + 1))
print(min) # the min
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate. This can also
be a list or tuple of such arguments, in which case a tuple of
corresponding aggregation results (each receiving the same
additional keyword arguments, if any) will be returned
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **safe** (*False*) – whether to ignore nan/inf values when dealing with
floating point values
* **Returns:**
the minimum value
#### mongo(pipeline, \_needs_frames=None, \_group_slices=None)
Adds 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
#
view = dataset.mongo([{"$skip": 1}, {"$limit": 2}])
#
# Sort by the number of objects in the `precictions` field
#
view = dataset.mongo([
{
"$addFields": {
"_sort_field": {
"$size": {"$ifNull": ["$predictions.detections", []]}
}
}
},
{"$sort": {"_sort_field": -1}},
{"$project": {"_sort_field": False}},
])
```
* **Parameters:**
**pipeline** – a MongoDB aggregation pipeline (list of dicts)
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### one(expr, exact=False)
Returns a single sample in this collection matching the expression.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
#
# Get a sample by filepath
#
# A random filepath in the dataset
filepath = dataset.take(1).first().filepath
# Get sample by filepath
sample = dataset.one(F("filepath") == filepath)
#
# Dealing with multiple matches
#
# Get a sample whose image is JPEG
sample = dataset.one(F("filepath").ends_with(".jpg"))
# Raises an error since there are multiple JPEGs
dataset.one(F("filepath").ends_with(".jpg"), exact=True)
```
* **Parameters:**
* **expr** –
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 evaluates to `True` for the sample to match
* **exact** (*False*) – whether to raise an error if multiple samples match
the expression
* **Raises:**
* **ValueError** – if no samples match the expression or if `exact=True`
* **and multiple samples match the expression** –
* **Returns:**
a [`fiftyone.core.sample.SampleView`](fiftyone.core.sample.md#fiftyone.core.sample.SampleView)
#### quantiles(field_or_expr, quantiles, expr=None, safe=False)
Computes the quantile(s) of the field values of a collection.
`None`-valued fields are ignored.
This aggregation is typically applied to *numeric* field types (or
lists of such types):
- [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField)
- [`fiftyone.core.fields.FloatField`](fiftyone.core.fields.md#fiftyone.core.fields.FloatField)
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",
numeric_field=1.0,
numeric_list_field=[1, 2, 3],
),
fo.Sample(
filepath="/path/to/image2.png",
numeric_field=4.0,
numeric_list_field=[1, 2],
),
fo.Sample(
filepath="/path/to/image3.png",
numeric_field=None,
numeric_list_field=None,
),
]
)
#
# Compute the quantiles of a numeric field
#
quantiles = dataset.quantiles("numeric_field", [0.1, 0.5, 0.9])
print(quantiles) # the quantiles
#
# Compute the quantiles of a numeric list field
#
quantiles = dataset.quantiles("numeric_list_field", [0.1, 0.5, 0.9])
print(quantiles) # the quantiles
#
# Compute the mean of a transformation of a numeric field
#
quantiles = dataset.quantiles(2 * (F("numeric_field") + 1), [0.1, 0.5, 0.9])
print(quantiles) # the quantiles
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate
* **quantiles** – the quantile or iterable of quantiles to compute. Each
quantile must be a numeric value in `[0, 1]`
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **safe** (*False*) – whether to ignore nan/inf values when dealing with
floating point values
* **Returns:**
the quantile or list of quantiles
#### register_run(run_key, config, results=None, overwrite=False, cleanup=True, cache=True)
Registers a run under the given key on this collection.
* **Parameters:**
* **run_key** – a run key
* **config** – a [`fiftyone.core.runs.RunConfig`](fiftyone.core.runs.md#fiftyone.core.runs.RunConfig)
* **results** (*None*) – an optional [`fiftyone.core.runs.RunResults`](fiftyone.core.runs.md#fiftyone.core.runs.RunResults)
* **overwrite** (*False*) – whether to allow overwriting an existing run of
the same type
* **cleanup** (*True*) – whether to execute an existing run’s
[`fiftyone.core.runs.Run.cleanup()`](fiftyone.core.runs.md#fiftyone.core.runs.Run.cleanup) method when overwriting
it
* **cache** (*True*) – whether to cache the results on the collection
#### reload()
Reloads the view.
Note that [`ClipView`](#fiftyone.core.clips.ClipView) instances are not singletons, so any
in-memory clips extracted from this view will not be updated by calling
this method.
#### rename_annotation_run(anno_key, new_anno_key)
Replaces the key for the given annotation run with a new key.
* **Parameters:**
* **anno_key** – an annotation key
* **new_anno_key** – a new annotation key
#### rename_brain_run(brain_key, new_brain_key)
Replaces the key for the given brain run with a new key.
* **Parameters:**
* **brain_key** – a brain key
* **new_brain_key** – a new brain key
#### rename_evaluation(eval_key, new_eval_key)
Replaces the key for the given evaluation with a new key.
* **Parameters:**
* **eval_key** – an evaluation key
* **new_anno_key** – a new evaluation key
#### rename_run(run_key, new_run_key)
Replaces the key for the given run with a new key.
* **Parameters:**
* **run_key** – a run key
* **new_run_key** – a new run key
#### save(fields=None)
Saves the clips in this view to the underlying dataset.
#### NOTE
This method is not a [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage);
it immediately writes the requested changes to the underlying
dataset.
#### WARNING
This will permanently delete any omitted or filtered contents from
the frames of the underlying dataset.
* **Parameters:**
**fields** (*None*) – an optional field or list of fields to save. If
specified, only these fields are overwritten
#### save_context(batch_size=None, batching_strategy=None)
Returns a context that can be used to save samples from this
collection according to a configurable batching strategy.
Examples:
```default
import random as r
import string as s
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("cifar10", split="test")
def make_label():
return "".join(r.choice(s.ascii_letters) for i in range(10))
# No save context
for sample in dataset.iter_samples(progress=True):
sample.ground_truth.label = make_label()
sample.save()
# Save using default batching strategy
with dataset.save_context() as context:
for sample in dataset.iter_samples(progress=True):
sample.ground_truth.label = make_label()
context.save(sample)
# Save in batches of 10
with dataset.save_context(batch_size=10) as context:
for sample in dataset.iter_samples(progress=True):
sample.ground_truth.label = make_label()
context.save(sample)
# Save every 0.5 seconds
with dataset.save_context(batch_size=0.5) as context:
for sample in dataset.iter_samples(progress=True):
sample.ground_truth.label = make_label()
context.save(sample)
```
* **Parameters:**
* **batch_size** (*None*) – the batch size to use. If a `batching_strategy`
is provided, this parameter configures the strategy as
described below. If no `batching_strategy` is provided, this
can either be an integer specifying the number of samples to
save in a batch (in which case `batching_strategy` is
implicitly set to `"static"`) or a float number of seconds
between batched saves (in which case `batching_strategy` is
implicitly set to `"latency"`)
* **batching_strategy** (*None*) –
the batching strategy to use for each
save operation. Supported values are:
- `"static"`: a fixed sample batch size for each save
- `"size"`: a target batch size, in bytes, for each save
- `"latency"`: a target latency, in seconds, between saves
By default, `fo.config.default_batcher` is used
* **Returns:**
a `SaveContext`
#### save_run_results(run_key, results, overwrite=True, cache=True)
Saves run results for the run with the given key.
* **Parameters:**
* **run_key** – a run key
* **results** – a [`fiftyone.core.runs.RunResults`](fiftyone.core.runs.md#fiftyone.core.runs.RunResults)
* **overwrite** (*True*) – whether to overwrite an existing result with the
same key
* **cache** (*True*) – whether to cache the results on the collection
#### schema(field_or_expr, expr=None, dynamic_only=False, \_doc_type=None, \_include_private=False)
Extracts the names and types of the attributes of a specified
embedded document field across all samples in the collection.
Schema aggregations are useful for detecting the presence and types of
dynamic attributes of [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) fields
across a collection.
Examples:
```default
import fiftyone as fo
dataset = fo.Dataset()
sample1 = fo.Sample(
filepath="image1.png",
ground_truth=fo.Detections(
detections=[
fo.Detection(
label="cat",
bounding_box=[0.1, 0.1, 0.4, 0.4],
foo="bar",
hello=True,
),
fo.Detection(
label="dog",
bounding_box=[0.5, 0.5, 0.4, 0.4],
hello=None,
)
]
)
)
sample2 = fo.Sample(
filepath="image2.png",
ground_truth=fo.Detections(
detections=[
fo.Detection(
label="rabbit",
bounding_box=[0.1, 0.1, 0.4, 0.4],
foo=None,
),
fo.Detection(
label="squirrel",
bounding_box=[0.5, 0.5, 0.4, 0.4],
hello="there",
),
]
)
)
dataset.add_samples([sample1, sample2])
#
# Get schema of all dynamic attributes on the detections in a
# `Detections` field
#
print(dataset.schema("ground_truth.detections", dynamic_only=True))
# {'foo': StringField, 'hello': [BooleanField, StringField]}
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **dynamic_only** (*False*) – whether to only include dynamically added
attributes
* **Returns:**
a dict mapping field names to [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
instances. If a field’s values takes multiple non-None types, the
list of observed types will be returned
#### select(sample_ids, ordered=False)
Selects the samples with the given IDs from the 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...
view = dataset.select(session.selected)
```
* **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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### select_by(field, values, ordered=False)
Selects the samples with the given field values from the 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.clips.TrajectoriesView.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
#
view = dataset.select_by("int", [1, 51, 11, 41, 21, 31])
print(view.head(6))
#
# Create a view containing samples whose `str` field have the given
# values, in order
#
view = dataset.select_by(
"str", ["1", "51", "11", "41", "21", "31"], ordered=True
)
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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### select_fields(field_names=None, meta_filter=None, \_allow_missing=False)
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
#
view = dataset.select_fields()
#
# Include only the `uniqueness` field (and the default fields) on
# each sample
#
view = dataset.select_fields("uniqueness")
#
# Include only the `mood` attribute (and the default attributes) of
# each `Detection` in the `ground_truth` field
#
view = dataset.select_fields("ground_truth.detections.mood")
```
* **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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### select_frames(frame_ids, omit_empty=True)
Selects the frames with the given IDs from the 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,
]
view = dataset.select_frames(frame_ids)
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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### select_group_slices(slices=None, media_type=None, flat=True, \_allow_mixed=False, \_force_mixed=False)
Selects the specified group slice(s) from the 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
#
view = dataset.select_group_slices("ego")
#
# Retrieve the samples from the "left" or "right" group slices
#
view = dataset.select_group_slices(["left", "right"])
#
# Select only the "left" and "right" group slices
#
view = dataset.select_group_slices(["left", "right"], flat=False)
#
# Retrieve all image samples
#
view = dataset.select_group_slices(media_type="image")
```
* **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)
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### select_groups(group_ids, ordered=False)
Selects the groups with the given IDs from the 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")
view = dataset.select_groups(group_ids)
assert set(view.values("group.id")) == set(group_ids)
view = dataset.select_groups(group_ids, ordered=True)
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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### select_labels(labels=None, ids=None, instance_ids=None, tags=None, fields=None, omit_empty=True)
Selects only the specified labels from the 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...
view = dataset.select_labels(labels=session.selected_labels)
#
# 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,
]
view = dataset.select_labels(ids=ids)
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_label_tags())
# Retrieve the labels via their tag
view = dataset.select_labels(tags="test")
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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### set_field(field, expr, \_allow_missing=False)
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 the `uniqueness` field that are less than
# 0.5 with `None`
#
view = dataset.set_field(
"uniqueness",
(F("uniqueness") >= 0.5).if_else(F("uniqueness"), None)
)
print(view.bounds("uniqueness"))
#
# Lower bound all object confidences in the `predictions` field at
# 0.5
#
view = dataset.set_field(
"predictions.detections.confidence", F("confidence").max(0.5)
)
print(view.bounds("predictions.detections.confidence"))
#
# Add a `num_predictions` property to the `predictions` field that
# contains the number of objects in the field
#
view = dataset.set_field(
"predictions.num_predictions",
F("$predictions.detections").length(),
)
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"
]
view = dataset.set_field(
"predictions.detections.is_animal", F("label").is_in(ANIMALS)
)
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 expression](https://docs.mongodb.com/manual/meta/aggregation-quick-reference/#aggregation-expressions)
that defines the field value to set
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### set_label_values(field_name, \*args, \*\*kwargs)
Sets the fields of the specified labels in the collection to the
given values.
You can use this method in two ways:
- **List syntax (recommended):** provide a list of dicts of the form
`{"sample_id": sample_id, "label_id": label_id, "value": value}`
specifying the sample IDs and label IDs of each label you want to
edit
- **Dict syntax:** provide a dict mapping label IDs to values
#### NOTE
This method is most efficient when you use the list syntax, which
includes the sample/frame ID of each label that you are modifying.
#### NOTE
This method is appropriate when you have the IDs of the labels you
wish to modify. See [`set_values()`](#fiftyone.core.clips.TrajectoriesView.set_values) and [`set_field()`](#fiftyone.core.clips.TrajectoriesView.set_field) if
your updates are not keyed by label ID.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
#
# Populate a new boolean attribute on all high confidence labels
#
view = dataset.filter_labels("predictions", F("confidence") > 0.99)
# Option 1 (recommended): provide label IDs and sample IDs
values = []
sample_ids, label_ids = view.values(["id", "predictions.detections.id"])
for sid, lids in zip(sample_ids, label_ids):
for lid in lids:
values.append({"sample_id": sid, "label_id": lid, "value": True})
dataset.set_label_values("predictions.detections.high_conf", values)
print(dataset.count("predictions.detections"))
print(len(values))
print(dataset.count_values("predictions.detections.high_conf"))
# Option 2: provide only label IDs
label_ids = view.values("predictions.detections.id", unwind=True)
values = {_id: True for _id in label_ids}
dataset.set_label_values("predictions.detections.high_conf", values)
print(dataset.count("predictions.detections"))
print(len(label_ids))
print(dataset.count_values("predictions.detections.high_conf"))
```
* **Parameters:**
* **field_name** – a field or `embedded.field.name`
* **values** –
the label values to set, in one of the following formats:
- a list of dicts of the form
`{"sample_id": sample_id, "label_id": label_id, "value": value}`
when setting sample-level labels
- a list of dicts of the form
`{"frame_id": frame_id, "label_id": label_id, "value": value}`
when setting frame-level labels
- a dict mapping label IDs to values
* **skip_none** (*False*) – whether to treat None data in `values` as
missing data that should not be set
* **dynamic** (*False*) – whether to declare dynamic attributes of embedded
document fields that are encountered
* **validate** (*True*) – whether to validate that the values are compliant
with the dataset schema before adding them
* **progress** (*False*) – whether to render a progress bar (True/False),
use the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
#### set_values(field_name, \*args, \*\*kwargs)
Sets the field or embedded field on each sample or frame in the
collection to the given values.
You can use this method in two ways:
- **Dict syntax (recommended):** provide `values` as a dict whose
keys specify the `key_field` values of the samples whose
`field_name` you want to set to the corresponding values
- **List syntax:** provide `values` as a list, one for each sample
in the collection on which you are invoking this method
#### NOTE
The most performant strategy for setting large numbers of field
values is to use the dict syntax with `key_field="id"` when
setting sample fields and `key_field="frames.id"` when setting
frame fields. All other syntaxes internally convert to these IDs
before ultimately performing the updates.
When setting a sample field `embedded.field.name` via the list
`values` syntax, this function is an efficient implementation of the
following loop:
```default
for sample, value in zip(sample_collection, values):
sample.embedded.field.name = value
sample.save()
```
When setting an embedded field that contains an array, say
`embedded.array.field.name`, via the list `values` syntax, this
function is an efficient implementation of the following loop:
```default
for sample, array_values in zip(sample_collection, values):
for doc, value in zip(sample.embedded.array, array_values):
doc.field.name = value
sample.save()
```
When setting a frame field `frames.embedded.field.name` via the list
`values` syntax, this function is an efficient implementation of the
following loop:
```default
for sample, frame_values in zip(sample_collection, values):
for frame, value in zip(sample.frames.values(), frame_values):
frame.embedded.field.name = value
sample.save()
```
When setting an embedded frame field that contains an array, say
`frames.embedded.array.field.name`, via the list `values` syntax,
this function is an efficient implementation of the following loop:
```default
for sample, frame_values in zip(sample_collection, values):
for frame, array_values in zip(sample.frames.values(), frame_values):
for doc, value in zip(frame.embedded.array, array_values):
doc.field.name = value
sample.save()
```
When setting a sample field `embedded.field.name` via the dict
`values` syntax, this function is an efficient implementation of the
following loop:
```default
for key, value in values.items():
sample = sample_collection.one(F(key_field) == key)
sample.embedded.field.name = value
sample.save()
```
When setting frame fields using the dict `values` syntax with a
frame-level `key_field`, this function is an efficient implementation
of the following loop:
```default
frames = sample_collection.to_frames(...)
for key, value in values.items():
frame = frames.one(F(key_field) == key)
frame.embedded.field.name = value
frame.save()
```
When setting frame fields using the dict `values` syntax with a
sample-level `key_field`, each value in `values` may either be a
list corresponding to the frames of the sample matching the given key,
or each value may itself be a dict mapping frame numbers to values. In
the latter case, this function is an efficient implementation of the
following loop:
```default
for key, frame_values in values.items():
sample = sample_collection.one(F(key_field) == key)
for frame_number, value in frame_values.items():
frame = sample[frame_number]
frame.embedded.field.name = value
sample.save()
```
You can also update list fields using the dict `values` syntaxes, in
which case this method is an efficient implementation of the natural
nested list modifications of the above sample/frame loops.
The dual function of [`set_values()`](#fiftyone.core.clips.TrajectoriesView.set_values) is [`values()`](#fiftyone.core.clips.TrajectoriesView.values), which can be
used to efficiently extract the values of a field or embedded field of
all samples in a collection as lists of values.
#### NOTE
If you are setting attributes of a nested list of labels, such as
attributes of the objects in a
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) field, then consider using
[`set_label_values()`](#fiftyone.core.clips.TrajectoriesView.set_label_values) instead for greater efficiency.
#### NOTE
If the values you are setting can be described by a
[`fiftyone.core.expressions.ViewExpression`](fiftyone.core.expressions.md#fiftyone.core.expressions.ViewExpression) applied to the
existing dataset contents, then consider using [`set_field()`](#fiftyone.core.clips.TrajectoriesView.set_field) +
[`save()`](fiftyone.core.view.md#fiftyone.core.view.DatasetView.save) for an even
more efficient alternative to explicitly iterating over the dataset
or calling [`values()`](#fiftyone.core.clips.TrajectoriesView.values) + [`set_values()`](#fiftyone.core.clips.TrajectoriesView.set_values) to perform the
update in-memory.
Examples:
```default
import random
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
#
# Create a new sample field
#
# list syntax
values = [random.random() for _ in range(len(dataset))]
dataset.set_values("random", values)
print(dataset.bounds("random"))
#
# Edit a frame field
#
# dict syntax
sample_ids = dataset.values("id")
values = {id: random.random() for id in sample_ids}
dataset.set_values("random", values, key_field="id")
print(dataset.bounds("random"))
#
# Add a tag to all low confidence labels
#
view = dataset.filter_labels("predictions", F("confidence") < 0.06)
# list syntax on a filtered view
tags = view.values("predictions.detections.tags")
for sample_tags in tags:
for detection_tags in sample_tags:
detection_tags.append("low_confidence")
view.set_values("predictions.detections.tags", tags)
print(view.count("predictions.detections")) # 447
print(dataset.count_label_tags()) # 447
#
# Create a new frame field
#
dataset = foz.load_zoo_dataset("quickstart-video")
# list syntax
values = []
for sample in dataset:
values.append([random.random() for _ in sample.frames])
dataset.set_values("frames.random", values)
print(dataset.bounds("frames.random"))
#
# Edit a frame field
#
# dict syntax
frame_ids = dataset.values("frames.id", unwind=True)
values = {id: random.random() for id in frame_ids}
dataset.set_values("frames.random", values, key_field="frames.id")
print(dataset.bounds("frames.random"))
```
* **Parameters:**
* **field_name** – a field or `embedded.field.name`
* **values** –
the field values to set, provided in either of the
following formats:
- **list syntax**: an iterable of values, one for each sample
in the collection. If `field_name` contains array fields,
the corresponding elements of `values` must be arrays of
the same lengths. When setting frame fields, each element
can either be an iterable of values (one for each existing
frame of the sample) or a dict mapping frame numbers to
values
- **dict syntax**: a dict whose keys specify the `key_field`
values of the samples for which to set `field_name` to
the corresponding values. When setting frame fields, you
can either provide a sample-level `key_field`, in which
case each corresponding value in `values` must be a list
or dict of per-frame field values to set as described in
the previous bullet, or you can provide a frame-level
`key_field`, in which case each key-value pair in
`values` represents a per-frame update
* **key_field** (*None*) – a key field to use when choosing which samples to
update when `values` is a dict
* **skip_none** (*False*) – whether to treat None data in `values` as
missing data that should not be set
* **expand_schema** (*True*) – whether to dynamically add new sample/frame
fields encountered to the dataset schema. If False, an error is
raised if the root `field_name` does not exist
* **dynamic** (*False*) – whether to declare dynamic attributes of embedded
document fields that are encountered
* **validate** (*True*) – whether to validate that the values are compliant
with the dataset schema before adding them
* **progress** (*False*) – whether to render a progress bar (True/False),
use the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead
#### shuffle(seed=None)
Randomly shuffles the samples in the 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
#
view = dataset.shuffle()
#
# Shuffle the samples with a fixed random seed
#
view = dataset.shuffle(seed=51)
```
* **Parameters:**
**seed** (*None*) – an optional random seed to use when shuffling the
samples
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### *property* skeletons
The keypoint skeletons of the underlying dataset.
See [`fiftyone.core.dataset.Dataset.skeletons()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.skeletons) for more
information.
#### skip(skip)
Omits the given number of samples from the head of the 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
#
view = dataset.skip(2)
```
* **Parameters:**
**skip** – the number of samples to skip. If a non-positive number is
provided, no samples are omitted
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### sort_by(field_or_expr, reverse=False, create_index=False)
Sorts the samples in the 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
#
view = dataset.sort_by("uniqueness", reverse=False)
#
# 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)
view = dataset.sort_by(small_boxes.length(), reverse=True)
#
# Performs a compound sort where samples are first sorted in
# descending or by number of detections and then in ascending order
# of uniqueness for samples with the same number of predictions
#
view = dataset.sort_by(
[
(F("predictions.detections").length(), -1),
("uniqueness", 1),
]
)
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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### sort_by_similarity(query, k=None, reverse=False, dist_field=None, brain_key=None)
Sorts the 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
view = dataset.sort_by_similarity(query_id, k=5)
#
# 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)
view = dataset.sort_by_similarity(query, k=5)
#
# Sort samples by their similarity to a text prompt
#
query = "kites high in the air"
view = dataset.sort_by_similarity(query, k=5)
```
* **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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### split_labels(in_field, out_field, filter=None)
Splits the labels from the given input field into the given output
field of the collection.
This method is typically invoked on a view that has filtered the
contents of the specified input field, so that the labels in the view
are moved to the output field and the remaining labels are left
in-place.
Alternatively, you can provide a `filter` expression that selects the
labels of interest to move in this collection.
* **Parameters:**
* **in_field** – the name of the input label field
* **out_field** – the name of the output label field, which will be
created if necessary
* **filter** (*None*) – a boolean
[`fiftyone.core.expressions.ViewExpression`](fiftyone.core.expressions.md#fiftyone.core.expressions.ViewExpression) to apply to
each label in the input field to determine whether to move it
(True) or leave it (False)
#### *property* static_transforms
The static transforms of the underlying dataset.
See [`fiftyone.core.dataset.Dataset.static_transforms()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.static_transforms) for more
information.
#### stats(include_media=False, include_indexes=False, compressed=False)
Returns stats about the collection on disk.
The `samples` keys refer to the sample documents stored in the
database.
For video datasets, the `frames` keys refer to the frame documents
stored in the database.
The `media` keys refer to the raw media associated with each sample
on disk.
The `index[es]` keys refer to the indexes associated with the
dataset.
Note that dataset-level metadata such as annotation runs are not
included in this computation.
* **Parameters:**
* **include_media** (*False*) – whether to include stats about the size of
the raw media in the collection
* **include_indexes** (*False*) – whether to include stats on the dataset’s
indexes
* **compressed** (*False*) – whether to return the sizes of collections in
their compressed form on disk (True) or the logical
uncompressed size of the collections (False). This option is
only supported for datasets (not views)
* **Returns:**
a stats dict
#### std(field_or_expr, expr=None, safe=False, sample=False)
Computes the standard deviation of the field values of the
collection.
`None`-valued fields are ignored.
This aggregation is typically applied to *numeric* field types (or
lists of such types):
- [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField)
- [`fiftyone.core.fields.FloatField`](fiftyone.core.fields.md#fiftyone.core.fields.FloatField)
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",
numeric_field=1.0,
numeric_list_field=[1, 2, 3],
),
fo.Sample(
filepath="/path/to/image2.png",
numeric_field=4.0,
numeric_list_field=[1, 2],
),
fo.Sample(
filepath="/path/to/image3.png",
numeric_field=None,
numeric_list_field=None,
),
]
)
#
# Compute the standard deviation of a numeric field
#
std = dataset.std("numeric_field")
print(std) # the standard deviation
#
# Compute the standard deviation of a numeric list field
#
std = dataset.std("numeric_list_field")
print(std) # the standard deviation
#
# Compute the standard deviation of a transformation of a numeric field
#
std = dataset.std(2 * (F("numeric_field") + 1))
print(std) # the standard deviation
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate. This can also
be a list or tuple of such arguments, in which case a tuple of
corresponding aggregation results (each receiving the same
additional keyword arguments, if any) will be returned
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **safe** (*False*) – whether to ignore nan/inf values when dealing with
floating point values
* **sample** (*False*) – whether to compute the sample standard deviation rather
than the population standard deviation
* **Returns:**
the standard deviation
#### sum(field_or_expr, expr=None, safe=False)
Computes the sum of the field values of the collection.
`None`-valued fields are ignored.
This aggregation is typically applied to *numeric* field types (or
lists of such types):
- [`fiftyone.core.fields.IntField`](fiftyone.core.fields.md#fiftyone.core.fields.IntField)
- [`fiftyone.core.fields.FloatField`](fiftyone.core.fields.md#fiftyone.core.fields.FloatField)
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",
numeric_field=1.0,
numeric_list_field=[1, 2, 3],
),
fo.Sample(
filepath="/path/to/image2.png",
numeric_field=4.0,
numeric_list_field=[1, 2],
),
fo.Sample(
filepath="/path/to/image3.png",
numeric_field=None,
numeric_list_field=None,
),
]
)
#
# Compute the sum of a numeric field
#
total = dataset.sum("numeric_field")
print(total) # the sum
#
# Compute the sum of a numeric list field
#
total = dataset.sum("numeric_list_field")
print(total) # the sum
#
# Compute the sum of a transformation of a numeric field
#
total = dataset.sum(2 * (F("numeric_field") + 1))
print(total) # the sum
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate. This can also
be a list or tuple of such arguments, in which case a tuple of
corresponding aggregation results (each receiving the same
additional keyword arguments, if any) will be returned
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **safe** (*False*) – whether to ignore nan/inf values when dealing with
floating point values
* **Returns:**
the sum
#### summary()
Returns a string summary of the view.
* **Returns:**
a string summary
#### sync_last_modified_at(include_frames=True)
Syncs the `last_modified_at` property(s) of the dataset.
Updates the `last_modified_at` property of the dataset if
necessary to incorporate any modification/deletion timestamps to its
samples.
If `include_frames==True`, the `last_modified_at` property of
each video sample is first updated if necessary to incorporate any
modification timestamps to its frames.
* **Parameters:**
**include_frames** (*True*) – whether to update the `last_modified_at`
property of video samples. Only applicable to datasets that
contain videos
#### tag_labels(tags, label_fields=None)
Adds the tag(s) to all labels in the specified label field(s) of
this collection, if necessary.
* **Parameters:**
* **tags** – a tag or iterable of tags
* **label_fields** (*None*) – an optional name or iterable of names of
[`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) fields. By default, all
label fields are used
#### tag_samples(tags)
Adds the tag(s) to all samples in this collection, if necessary.
* **Parameters:**
**tags** – a tag or iterable of tags
#### *property* tags
The list of tags of the underlying dataset.
See [`fiftyone.core.dataset.Dataset.tags()`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.tags) for more information.
#### tail(num_samples=3)
Returns a list of the last few samples in the collection.
If fewer than `num_samples` samples are in the collection, only
the available samples are returned.
* **Parameters:**
**num_samples** (*3*) – the number of samples
* **Returns:**
a list of [`fiftyone.core.sample.Sample`](fiftyone.core.sample.md#fiftyone.core.sample.Sample) objects
#### take(size, seed=None)
Randomly samples the given number of samples from the 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
#
view = dataset.take(2)
#
# Take two random samples from the dataset with a fixed seed
#
view = dataset.take(2, seed=51)
```
* **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
* **Returns:**
a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView)
#### to_clips(field_or_expr, \*\*kwargs)
Creates a view that contains one sample per clip defined by the
given field or expression in the 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.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
#
clips = (
dataset
.filter_labels("frames.detections", F("label") == "road sign")
.to_clips("frames.detections")
)
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")
clips = dataset.to_clips(signs.length() >= 2)
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
* **other_fields** (*None*) –
controls whether sample fields other than the
default sample fields are included. Can be any of the
following:
- a field or list of fields to include
- `True` to include all other fields
- `None`/`False` to include no other fields
* **include_indexes** (*False*) – whether to recreate any custom indexes on
`field_or_expr` and `other_fields` on the clips view (True)
or a list of specific indexes or index prefixes to recreate.
By default, no custom indexes are recreated
* **tol** (*0*) – the maximum number of false frames that can be overlooked
when generating clips. Only applicable when `field_or_expr`
is a frame-level list field or expression
* **min_len** (*0*) – the minimum allowable length of a clip, in frames.
Only applicable when `field_or_expr` is a frame-level list
field or an expression
* **trajectories** (*False*) – whether to create clips for each unique
object trajectory defined by their `(label, index)`. Only
applicable when `field_or_expr` is a frame-level field
* **Returns:**
a [`fiftyone.core.clips.ClipsView`](#fiftyone.core.clips.ClipsView)
#### to_dict(rel_dir=None, include_private=False, include_frames=False, frame_labels_dir=None, pretty_print=False)
Returns a JSON dictionary representation of the view.
* **Parameters:**
* **rel_dir** (*None*) – a relative directory to remove from the
`filepath` of each sample, if possible. The path is converted
to an absolute path (if necessary) via
[`fiftyone.core.storage.normalize_path()`](fiftyone.core.storage.md#fiftyone.core.storage.normalize_path). The typical use
case for this argument is that your source data lives in a
single directory and you wish to serialize relative, rather
than absolute, paths to the data within that directory
* **include_private** (*False*) – whether to include private fields
* **include_frames** (*False*) – whether to include the frame labels for
video samples
* **frame_labels_dir** (*None*) – a directory in which to write per-sample
JSON files containing the frame labels for video samples. If
omitted, frame labels will be included directly in the returned
JSON dict (which can be quite quite large for video datasets
containing many frames). Only applicable to datasets that
contain videos when `include_frames` is True
* **pretty_print** (*False*) – whether to render frame labels JSON in human
readable format with newlines and indentations. Only applicable
to datasets that contain videos when a `frame_labels_dir` is
provided
* **Returns:**
a JSON dict
#### to_evaluation_patches(eval_key, \*\*kwargs)
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.clips.TrajectoriesView.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
#
view = dataset.to_evaluation_patches("eval")
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`](fiftyone.core.labels.md#fiftyone.core.labels.Polylines), or
[`fiftyone.core.labels.Keypoints`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoints)
* **other_fields** (*None*) –
controls whether fields other than the
ground truth/predicted fields and the default sample fields are
included. Can be any of the following:
- a field or list of fields to include
- `True` to include all other fields
- `None`/`False` to include no other fields
* **include_indexes** (*False*) – whether to recreate any custom indexes on
the ground truth/predicted fields and `other_fields` on the
patches view (True) or a list of specific indexes or index
prefixes to recreate. By default, no custom indexes are
recreated
* **Returns:**
a [`fiftyone.core.patches.EvaluationPatchesView`](fiftyone.core.patches.md#fiftyone.core.patches.EvaluationPatchesView)
#### to_frames(\*\*kwargs)
Creates a view that contains one sample per frame in the 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
#
frames = dataset.to_frames(sample_frames=True)
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)
frames = view.to_frames(max_fps=1)
print(frames)
session.view = frames
```
* **Parameters:**
* **sample_frames** (*False*) – whether to assume that the frame images have
already been sampled at locations stored in the `filepath`
field of each frame (False), or whether to sample the video
frames now according to the specified parameters (True)
* **fps** (*None*) – an optional frame rate at which to sample each video’s
frames
* **max_fps** (*None*) – an optional maximum frame rate at which to sample.
Videos with frame rate exceeding this value are downsampled
* **size** (*None*) – an optional `(width, height)` at which to sample
frames. A dimension can be -1, in which case the aspect ratio
is preserved. Only applicable when `sample_frames=True`
* **min_size** (*None*) – an optional minimum `(width, height)` for each
frame. A dimension can be -1 if no constraint should be
applied. The frames are resized (aspect-preserving) if
necessary to meet this constraint. Only applicable when
`sample_frames=True`
* **max_size** (*None*) – an optional maximum `(width, height)` for each
frame. A dimension can be -1 if no constraint should be
applied. The frames are resized (aspect-preserving) if
necessary to meet this constraint. Only applicable when
`sample_frames=True`
* **sparse** (*False*) – whether to only sample frame images for frame
numbers for which [`fiftyone.core.frame.Frame`](fiftyone.core.frame.md#fiftyone.core.frame.Frame) instances
exist in the input collection. This parameter has no effect
when `sample_frames==False` since frames must always exist in
order to have `filepath` information use
* **output_dir** (*None*) – an optional output directory in which to write
the sampled frames. By default, the frames are written in
folders with the same basename of each video
* **rel_dir** (*None*) – a relative directory to remove from the filepath of
each video, if possible. The path is converted to an absolute
path (if necessary) via
[`fiftyone.core.storage.normalize_path()`](fiftyone.core.storage.md#fiftyone.core.storage.normalize_path). This argument can
be used in conjunction with `output_dir` to cause the sampled
frames to be written in a nested directory structure within
`output_dir` matching the shape of the input video’s folder
structure
* **frames_patt** (*None*) – a pattern specifying the filename/format to use
to write or check or existing sampled frames, e.g.,
`"%%06d.jpg"`. The default value is
`fiftyone.config.default_sequence_idx + fiftyone.config.default_image_ext`
* **force_sample** (*False*) – whether to resample videos whose sampled
frames already exist. Only applicable when
`sample_frames=True`
* **skip_failures** (*True*) – whether to gracefully continue without
raising an error if a video cannot be sampled
* **verbose** (*False*) – whether to log information about the frames that
will be sampled, if any
* **include_indexes** (*False*) – whether to recreate any custom frame
indexes on the frames view (True) or a list of specific indexes
or index prefixes to recreate. By default, no custom indexes
are recreated
* **Returns:**
a [`fiftyone.core.video.FramesView`](fiftyone.core.video.md#fiftyone.core.video.FramesView)
#### to_json(rel_dir=None, include_private=False, include_frames=False, frame_labels_dir=None, pretty_print=False)
Returns a JSON string representation of the collection.
The samples will be written as a list in a top-level `samples` field
of the returned dictionary.
* **Parameters:**
* **rel_dir** (*None*) – a relative directory to remove from the
`filepath` of each sample, if possible. The path is converted
to an absolute path (if necessary) via
[`fiftyone.core.storage.normalize_path()`](fiftyone.core.storage.md#fiftyone.core.storage.normalize_path). The typical use
case for this argument is that your source data lives in a
single directory and you wish to serialize relative, rather
than absolute, paths to the data within that directory
* **include_private** (*False*) – whether to include private fields
* **include_frames** (*False*) – whether to include the frame labels for
video samples
* **frame_labels_dir** (*None*) – a directory in which to write per-sample
JSON files containing the frame labels for video samples. If
omitted, frame labels will be included directly in the returned
JSON dict (which can be quite quite large for video datasets
containing many frames). Only applicable to datasets that
contain videos when `include_frames` is True
* **pretty_print** (*False*) – whether to render the JSON in human readable
format with newlines and indentations
* **Returns:**
a JSON string
#### to_patches(field, \*\*kwargs)
Creates a view that contains one sample per object patch in the
specified field of the collection.
Fields other than `field` and the default sample fields will not be
included in the returned view. A `sample_id` field will be added that
records the sample ID from which each patch was taken.
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
#
view = dataset.to_patches("ground_truth")
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)
* **other_fields** (*None*) –
controls whether fields other than `field`
and the default sample fields are included. Can be any of the
following:
- a field or list of fields to include
- `True` to include all other fields
- `None`/`False` to include no other fields
* **keep_label_lists** (*False*) – whether to store the patches in label
list fields of the same type as the input collection rather
than using their single label variants
* **include_indexes** (*False*) – whether to recreate any custom indexes on
`field` and `other_fields` on the patches view (True) or a
list of specific indexes or index prefixes to recreate. By
default, no custom indexes are recreated
* **Returns:**
a [`fiftyone.core.patches.PatchesView`](fiftyone.core.patches.md#fiftyone.core.patches.PatchesView)
#### to_torch(get_item, , index_field='id', vectorize=False, skip_failures=False, local_process_group=None)
Constructs a [`torch.utils.data.Dataset`](https://docs.pytorch.org/docs/stable/data.html#torch.utils.data.Dataset) that loads data
from this collection via the provided
[`fiftyone.utils.torch.GetItem`](fiftyone.utils.torch.md#fiftyone.utils.torch.GetItem) instance.
* **Parameters:**
* **get_item** – a [`fiftyone.utils.torch.GetItem`](fiftyone.utils.torch.md#fiftyone.utils.torch.GetItem)
* **index_field** ( *"id"*) – the dotted field path that defines the
dataset’s rows. The default `"id"` yields one row per
sample. Use a list-valued path such as `"frames.id"` or
`"ground_truth.detections.id"` to fan out into one row per
frame, detection, etc.
* **vectorize** (*False*) – whether to load and cache the required fields
from the sample collection upfront (True) or lazily load the
values from each sample when items are retrieved (False).
Vectorizing gives faster data loading times, but you must have
enough memory to store the required field values for the entire
sample collection. When `vectorize=True`, all field values
must be serializable; ie `pickle.dumps(field_value)` must not
raise an error
* **skip_failures** (*False*) – whether to skip failures that occur when
calling `get_item`. If True, the exception will be returned
rather than the intended field values
* **local_process_group** (*None*) – the local process group. Only used
during distributed training
* **Returns:**
a [`torch.utils.data.Dataset`](https://docs.pytorch.org/docs/stable/data.html#torch.utils.data.Dataset)
#### to_trajectories(field, \*\*kwargs)
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
#
trajectories = (
dataset
.filter_labels("frames.detections", F("label") == "vehicle")
.to_trajectories("frames.detections")
)
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)
* **other_fields** (*None*) –
controls whether sample fields other than the
default sample fields are included. Can be any of the
following:
- a field or list of fields to include
- `True` to include all other fields
- `None`/`False` to include no other fields
* **include_indexes** (*False*) – whether to recreate any custom indexes on
`other_fields` on the clips view (True) or a list of specific
indexes or index prefixes to recreate. By default, no custom
indexes are recreated
* **tol** (*0*) – the maximum number of false frames that can be overlooked
when generating clips
* **min_len** (*0*) – the minimum allowable length of a clip, in frames
* **Returns:**
a [`fiftyone.core.clips.TrajectoriesView`](#fiftyone.core.clips.TrajectoriesView)
#### untag_labels(tags, label_fields=None)
Removes the tag from all labels in the specified label field(s) of
this collection, if necessary.
* **Parameters:**
* **tags** – a tag or iterable of tags
* **label_fields** (*None*) – an optional name or iterable of names of
[`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) fields. By default, all
label fields are used
#### untag_samples(tags)
Removes the tag(s) from all samples in this collection, if
necessary.
* **Parameters:**
**tags** – a tag or iterable of tags
#### update_run_config(run_key, config)
Updates the run config for the run with the given key.
* **Parameters:**
* **run_key** – a run key
* **config** – a [`fiftyone.core.runs.RunConfig`](fiftyone.core.runs.md#fiftyone.core.runs.RunConfig)
#### update_samples(update_fcn, skip_failures=True, parallelize_method=None, num_workers=None, batch_method=None, batch_size=None, progress=None)
Applies the given function to each sample in the collection and
saves the resulting sample edits.
By default, a multiprocessing pool is used to parallelize the work,
unless this method is called in a daemon process (subprocess), in which
case no workers are used.
This function effectively performs the following map operation with the
outer loop in parallel:
```default
for batch_view in fou.iter_slices(sample_collection, batch_size):
for sample in batch_view.iter_samples(autosave=True):
map_fcn(sample)
```
Example:
```default
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("cifar10", split="train")
view = dataset.select_fields("ground_truth")
def update_fcn(sample):
sample.ground_truth.label = sample.ground_truth.label.upper()
view.update_samples(update_fcn)
print(dataset.count_values("ground_truth.label"))
```
* **Parameters:**
* **update_fcn** – a function to apply to each sample in the collection
* **skip_failures** (*True*) – whether to gracefully continue without
raising an error if the update function raises an exception for
a sample
* **parallelize_method** (*None*) – the parallelization method to use.
Supported values are `{"process", "thread"}`. The default is
`fiftyone.config.default_parallelization_method`
* **num_workers** (*None*) – the number of workers to use. When using
process parallelism, this defaults to
`fiftyone.config.default_process_pool_workers` if the value
is set, else
[`fiftyone.core.utils.recommend_process_pool_workers()`](fiftyone.core.utils.md#fiftyone.core.utils.recommend_process_pool_workers)
workers are used. If this value is <= 1, all work is done in
the main process
* **batch_method** (*None*) – whether to use IDs (`"id"`) or slices
(`"slice"`) to assign samples to workers
* **batch_size** (*None*) – an optional number of samples to distribute to
each worker at a time. By default, samples are evenly
distributed to workers with one batch per worker
* **progress** (*None*) – whether to render a progress bar (True/False), use
the default value `fiftyone.config.show_progress_bars`
(None), or a progress callback function to invoke instead, or
“workers” to render per-worker progress bars
#### validate_field_type(path, ftype=None, embedded_doc_type=None, subfield=None)
Validates that the collection has a field of the given type.
* **Parameters:**
* **path** – a field name or `embedded.field.name`
* **ftype** (*None*) – an optional field type or iterable of types to
enforce. Must be subclass(es) of
[`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
* **embedded_doc_type** (*None*) – an optional embedded document type or
iterable of types to enforce. Must be subclass(es) of
[`fiftyone.core.odm.BaseEmbeddedDocument`](fiftyone.core.odm.md#fiftyone.core.odm.BaseEmbeddedDocument)
* **subfield** (*None*) – an optional subfield type or iterable of subfield
types to enforce. Must be subclass(es) of
[`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
* **Raises:**
**ValueError** – if the field does not exist or does not have the
expected type
#### validate_fields_exist(fields, include_private=False)
Validates that the collection has field(s) with the given name(s).
If embedded field names are provided, only the root field is checked.
* **Parameters:**
* **fields** – a field name or iterable of field names
* **include_private** (*False*) – whether to include private fields when
checking for existence
* **Raises:**
**ValueError** – if one or more of the fields do not exist
#### values(field_or_expr, expr=None, missing_value=None, unwind=False, \_allow_missing=False, \_big_result=True, \_raw=False, \_field=None, \_enforce_natural_order=True)
Extracts the values of a field from all samples in the collection.
Values aggregations are useful for efficiently extracting a slice of
field or embedded field values across all samples in a collection. See
the examples below for more details.
The dual function of [`values()`](#fiftyone.core.clips.TrajectoriesView.values) is [`set_values()`](#fiftyone.core.clips.TrajectoriesView.set_values), which can be
used to efficiently set a field or embedded field of all samples in a
collection by providing lists of values of same structure returned by
this aggregation.
#### NOTE
Unlike other aggregations, [`values()`](#fiftyone.core.clips.TrajectoriesView.values) does not automatically
unwind list fields, which ensures that the returned values match
the potentially-nested structure of the documents.
You can opt-in to unwinding specific list fields using the `[]`
syntax, or you can pass the optional `unwind=True` parameter to
unwind all supported list fields. See
[Aggregating list fields](../user_guide/using_aggregations.md#aggregations-list-fields) for more information.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = fo.Dataset()
dataset.add_samples(
[
fo.Sample(
filepath="/path/to/image1.png",
numeric_field=1.0,
numeric_list_field=[1, 2, 3],
),
fo.Sample(
filepath="/path/to/image2.png",
numeric_field=4.0,
numeric_list_field=[1, 2],
),
fo.Sample(
filepath="/path/to/image3.png",
numeric_field=None,
numeric_list_field=None,
),
]
)
#
# Get all values of a field
#
values = dataset.values("numeric_field")
print(values) # [1.0, 4.0, None]
#
# Get all values of a list field
#
values = dataset.values("numeric_list_field")
print(values) # [[1, 2, 3], [1, 2], None]
#
# Get all values of transformed field
#
values = dataset.values(2 * (F("numeric_field") + 1))
print(values) # [4.0, 10.0, None]
#
# Get values from a label list field
#
dataset = foz.load_zoo_dataset("quickstart")
# list of `Detections`
detections = dataset.values("ground_truth")
# list of lists of `Detection` instances
detections = dataset.values("ground_truth.detections")
# list of lists of detection labels
labels = dataset.values("ground_truth.detections.label")
```
* **Parameters:**
* **field_or_expr** –
a field name, `embedded.field.name`,
[`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)
defining the field or expression to aggregate. This can also
be a list or tuple of such arguments, in which case a tuple of
corresponding aggregation results (each receiving the same
additional keyword arguments, if any) will be returned
* **expr** (*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)
to apply to `field_or_expr` (which must be a field) before
aggregating
* **missing_value** (*None*) – a value to insert for missing or
`None`-valued fields
* **unwind** (*False*) – whether to automatically unwind all recognized list
fields (True) or unwind all list fields except the top-level
sample field (-1)
* **Returns:**
the list of values
#### view()
Returns a copy of this view.
* **Returns:**
a `DatasetView`
#### write_json(json_path, rel_dir=None, include_private=False, include_frames=False, frame_labels_dir=None, pretty_print=False)
Writes the collection to disk in JSON format.
* **Parameters:**
* **json_path** – the path to write the JSON
* **rel_dir** (*None*) – a relative directory to remove from the
`filepath` of each sample, if possible. The path is converted
to an absolute path (if necessary) via
[`fiftyone.core.storage.normalize_path()`](fiftyone.core.storage.md#fiftyone.core.storage.normalize_path). The typical use
case for this argument is that your source data lives in a
single directory and you wish to serialize relative, rather
than absolute, paths to the data within that directory
* **include_private** (*False*) – whether to include private fields
* **include_frames** (*False*) – whether to include the frame labels for
video samples
* **frame_labels_dir** (*None*) – a directory in which to write per-sample
JSON files containing the frame labels for video samples. If
omitted, frame labels will be included directly in the returned
JSON dict (which can be quite quite large for video datasets
containing many frames). Only applicable to datasets that
contain videos when `include_frames` is True
* **pretty_print** (*False*) – whether to render the JSON in human readable
format with newlines and indentations
### fiftyone.core.clips.make_clips_dataset(sample_collection, field_or_expr, other_fields=None, include_indexes=False, tol=0, min_len=0, trajectories=False, name=None, persistent=False, \_generated=False)
Creates a dataset that contains one sample per clip defined by the
given field or expression in the collection.
The returned dataset 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
In addition, sample-level fields will be added for certain clipping
strategies:
- When `field_or_expr` is a temporal detection(s) field, the field
will be converted to a [`fiftyone.core.labels.Classification`](fiftyone.core.labels.md#fiftyone.core.labels.Classification)
field
- When `trajectories` is True, a sample-level label field will be added
recording the `label` and `index` of each trajectory
#### NOTE
The returned dataset will directly use the frame collection of the
input dataset.
* **Parameters:**
* **sample_collection** – a
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **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
* **other_fields** (*None*) –
controls whether sample fields other than the
default sample fields are included. Can be any of the following:
- a field or list of fields to include
- `True` to include all other fields
- `None`/`False` to include no other fields
* **include_indexes** (*False*) – whether to recreate any custom indexes on
`field_or_expr` and `other_fields` on the new dataset (True)
or a list of specific indexes or index prefixes to recreate.
By default, no custom indexes are recreated
* **tol** (*0*) – the maximum number of false frames that can be overlooked when
generating clips. Only applicable when `field_or_expr` is a
frame-level list field or expression
* **min_len** (*0*) – the minimum allowable length of a clip, in frames. Only
applicable when `field_or_expr` is a frame-level list field or an
expression
* **trajectories** (*False*) – whether to create clips for each unique object
trajectory defined by their `(label, index)`. Only applicable
when `field_or_expr` is a frame-level field
* **name** (*None*) – a name for the dataset
* **persistent** (*False*) – whether the dataset should persist in the database
after the session terminates
* **Returns:**
a [`fiftyone.core.dataset.Dataset`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset)