fiftyone.core.aggregations.HistogramValues

class documentation

class HistogramValues(Aggregation): (source)

Constructor: HistogramValues(field_or_expr, expr, bins, range, auto)

Computes a histogram of the field values in a collection.

This aggregation is typically applied to numeric or date field types (or lists of such types):

Examples:

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
#

aggregation = fo.HistogramValues("numeric_field", bins=50)
counts, edges, other = dataset.aggregate(aggregation)

plot_hist(counts, edges)
plt.show(block=False)

#
# Compute the histogram of a numeric list field
#

aggregation = fo.HistogramValues("numeric_list_field", bins=50)
counts, edges, other = dataset.aggregate(aggregation)

plot_hist(counts, edges)
plt.show(block=False)

#
# Compute the histogram of a transformation of a numeric field
#

aggregation = fo.HistogramValues(2 * (F("numeric_field") + 1), bins=50)
counts, edges, other = dataset.aggregate(aggregation)

plot_hist(counts, edges)
plt.show(block=False)

Parameters
field_or_expr	a field name, `embedded.field.name`, `fiftyone.core.expressions.ViewExpression`, or MongoDB expression defining the field or expression to aggregate
expr	a `fiftyone.core.expressions.ViewExpression` or MongoDB expression to apply to `field_or_expr` (which must be a field) before aggregating
bins	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 computed from the bounds of the field
range	a `(lower, upper)` tuple specifying a range in which to generate equal-width bins. Only applicable when `bins` is an integer or `None`
auto	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

Method	`__init__`	Undocumented
Method	`default_result`	Returns the default result for this aggregation.
Method	`parse_result`	Parses the output of `to_mongo`.
Method	`to_mongo`	Returns the MongoDB aggregation pipeline for this aggregation.
Method	`_compute_bin_edges`	Undocumented
Method	`_kwargs`	Returns a list of `[name, value]` lists describing the parameters of this aggregation instance.
Method	`_parse_args`	Undocumented
Method	`_parse_edges`	Undocumented
Method	`_parse_result_auto`	Undocumented
Method	`_parse_result_edges`	Undocumented
Instance Variable	`_auto`	Undocumented
Instance Variable	`_bins`	Undocumented
Instance Variable	`_edges`	Undocumented
Instance Variable	`_field_type`	Undocumented
Instance Variable	`_is_datetime`	Undocumented
Instance Variable	`_last_edges`	Undocumented
Instance Variable	`_num_bins`	Undocumented
Instance Variable	`_range`	Undocumented

Inherited from Aggregation:

Method	`__eq__`	Undocumented
Method	`__repr__`	Undocumented
Method	`__str__`	Undocumented
Property	`field_name`	The name of the field being computed on, if any.
Property	`safe`	Whether nan/inf values will be ignored when dealing with floating point values.
Class Method	`_from_dict`	Creates an `Aggregation` instance from a serialized JSON dict representation of it.
Method	`_needs_frames`	Whether the aggregation requires frame labels of video samples to be attached.
Method	`_needs_group_slices`	Whether the aggregation requires group slice(s) to be attached.
Method	`_serialize`	Returns a JSON dict representation of the `Aggregation`.
Instance Variable	`_expr`	Undocumented
Instance Variable	`_field_name`	Undocumented
Instance Variable	`_safe`	Undocumented
Instance Variable	`_uuid`	Undocumented
Property	`_has_big_result`	Whether the aggregation's result is returned across multiple documents.
Property	`_is_big_batchable`	Whether the aggregation has big results and its pipeline is defined by a single `$project` stage and thus can be combined with other such aggregations.

def __init__(self, field_or_expr, expr=None, bins=None, range=None, auto=False): (source) ¶

overrides fiftyone.core.aggregations.Aggregation.__init__

Undocumented

def default_result(self): (source) ¶

overrides fiftyone.core.aggregations.Aggregation.default_result

Returns the default result for this aggregation.

Returns
a tuple of	counts: `[]` edges: `[]` other: `0`

def parse_result(self, d): (source) ¶

overrides fiftyone.core.aggregations.Aggregation.parse_result

Parses the output of to_mongo.

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

def to_mongo(self, sample_collection, context=None): (source) ¶

overrides fiftyone.core.aggregations.Aggregation.to_mongo

Returns the MongoDB aggregation pipeline for this aggregation.

Parameters
sample_collection	the `fiftyone.core.collections.SampleCollection` to which the aggregation is being applied
context:`None`	a path context from which to resolve
Returns
a MongoDB aggregation pipeline (list of dicts)