public final class Histogram extends Object
The bin-size is always 1, so each bin corresponds to a discrete integer.
This can be used to record a discrete probability distribution, and is typically used in the Anchor software to record the distribution of image voxel intensity values.
Note that this is dense implementation and memory is allocated to store all values from minValue
to maxValue
(inclusive). This can be a lot of memory for e.g. unsigned-short
value types. However, it allows for a maximally efficient incrementing through voxels in an
image, without intermediate structures.
Modifier and Type | Class and Description |
---|---|
static interface |
Histogram.BinConsumer
Consumes a bin and corresponding count.
|
Constructor and Description |
---|
Histogram(int maxValue)
Constructs with a maximum value, and assuming a minimum value of 0.
|
Histogram(int minValue,
int maxValue)
Constructs with a minimum and maximum value.
|
Modifier and Type | Method and Description |
---|---|
void |
addHistogram(Histogram other)
Adds the counts from another histogram to the current object.
|
int |
calculateMaximum()
Calculates the maximum value with non zero-count among the histogram values.
|
int |
calculateMinimum()
Calculates the minimum value with non zero-count among the histogram values.
|
int |
calculateMode()
Calculates the mode of the histogram values.
|
long |
calculateSum()
Calculates the sum of all values in the distribution considering their counts.
|
long |
calculateSumCubes()
Calculates the cube of the squares of all values in the distribution considering their
counts.
|
long |
calculateSumSquares()
Calculates the sum of the squares of all values in the distribution considering their
counts.
|
long |
countMatching(java.util.function.IntPredicate predicate)
Gets the total count of all values that match a predicate.
|
Histogram |
cropRemoveLargerValues(long maxCount)
Like
cropRemoveSmallerValues(long) but larger values are removed rather than smaller
values if the total count is too high. |
Histogram |
cropRemoveSmallerValues(long maxCount)
Creates a
Histogram reusing the bins in the current histogram, but with an upper
limit on the total count. |
Histogram |
duplicate()
Creates a deep-copy of the current object.
|
int |
getCount(int value)
The count corresponding to a particular value.
|
int |
getMaxValue()
Maximum possible value in the histogram (inclusive).
|
long |
getTotalCount()
The total count across values in the histogram.
|
boolean |
hasNonZeroCount(int threshold)
Whether at least one value, greater or equal to
startMin has non-zero count? |
void |
incrementValue(int value)
Increments the count for a particular value by one.
|
void |
incrementValueBy(int value,
int increase)
Increments the count for a particular value.
|
void |
incrementValueBy(int value,
long increase)
|
boolean |
isEmpty()
If no value exists in the histogram with a count greater than zero.
|
void |
iterateValues(Histogram.BinConsumer consumer)
Calls
consumer for every value, increasing from min to max. |
void |
iterateValuesUntil(int limit,
Histogram.BinConsumer consumer)
Calls
consumer for every value until a limit, increasing from min to limit . |
double |
mean()
Calculates the mean of the histogram values, considering their frequency.
|
double |
mean(double power)
Calculates the mean of the values in the distribution, if each value is raised to a power.
|
double |
mean(double power,
double subtractValue)
Like
mean(double) but a value may be subtracted before raising to a power. |
int |
quantile(double quantile)
Calculates the corresponding value for a particular quantile in the distribution of
values in the histogram.
|
void |
removeBelowThreshold(int threshold)
All values less than
threshold are removed. |
void |
reset()
Sets the count for all values to 0.
|
int |
size()
The size of the range of values in the histogram.
|
double |
standardDeviation()
Calculates the standard-deviation of the distribution represented by the histogram.
|
Histogram |
threshold(java.util.function.DoublePredicate predicate)
Generates a new histogram containing only values that match a predicate.
|
String |
toString()
A string representation of what's in the histogram.
|
void |
transferCount(int valueFrom,
int valueTo)
Moves all count for a particular value and adds it to the count for another.
|
double |
variance()
Calculates the variance of the distribution represented by the histogram.
|
void |
zeroValue(int value)
Sets the count for a particular value to 0.
|
public Histogram(int maxValue)
maxValue
- maximum possible value in the histogram (inclusive).public Histogram(int minValue, int maxValue)
minValue
- minimum possible value in the histogram (inclusive).maxValue
- maximum possible value in the histogram (inclusive).public Histogram duplicate()
public void reset()
public void zeroValue(int value)
value
- the value whose count is zeroed.public void transferCount(int valueFrom, int valueTo)
valueFrom
- the value whose count is moved, after which it's count is set to zero.valueTo
- the value to which the count for valueFrom
is added.public void incrementValue(int value)
value
- the value whose count will be incremented by one.public void incrementValueBy(int value, int increase)
value
- the value whose count will be incremented.increase
- how much to increase the count by.public void incrementValueBy(int value, long increase)
value
- the value whose count will be incremented.increase
- how much to increase the count by.ArithmeticException
- if increase cannot be converted to an int
safely.public void removeBelowThreshold(int threshold)
threshold
are removed.threshold
- values greater or equal to this are kept in the histogram, lesser values are
removed.public boolean isEmpty()
public int getCount(int value)
value
- the value (the bin) to find a count for.public int size()
This is equivalent to (maxValue - minValue + 1)
.
public void addHistogram(Histogram other) throws OperationFailedException
Both histograms must have identical minimum and maximum values, and therefore represent the same range of values.
other
- the histogram to add.OperationFailedException
- if the histograms do have identical minimum and maximum
values.public double mean() throws OperationFailedException
Specifically, this is the mean of value * countFor(value)
across all values.
OperationFailedException
- if the histogram has no values.public int quantile(double quantile) throws OperationFailedException
A quantile of 0.3, would return the minimal value, greater or equal to at least 30% of the count.
quantile
- the quantile, in the interval [0, 1]
.OperationFailedException
- if the histogram has no values, or the quantile is outside
acceptable bounds.public boolean hasNonZeroCount(int threshold)
startMin
has non-zero count?threshold
- only values greater or equal to threshold
are considered. Use 0 for
all values.public int calculateMode() throws OperationFailedException
The mode is the most frequently occurring item.
OperationFailedException
- if the histogram has no values.public int calculateMaximum() throws OperationFailedException
OperationFailedException
- if the histogram has no values.public int calculateMinimum() throws OperationFailedException
OperationFailedException
- if the histogram has no values.public long calculateSum()
Specifically, the sum is value * countFor(value)
across all values.
public long calculateSumSquares()
Specifically, the sum is value^2 * countFor(value)
across all values.
public long calculateSumCubes()
Specifically, the sum is value^3 * countFor(value)
across all values.
public double standardDeviation() throws OperationFailedException
OperationFailedException
- if the histogram has no values.public double variance() throws OperationFailedException
OperationFailedException
- if the histogram has no values.public long countMatching(java.util.function.IntPredicate predicate)
predicate
- the predicate a value must match to be included in the count.public Histogram threshold(java.util.function.DoublePredicate predicate)
This is an immutable operation. The existing histogram's values are unchanged.
predicate
- a condition that must hold on the value for it to be included in the created
histogram.Histogram
containing values and corresponding counts from
this object, but only if they fulfill the predicate.public String toString()
public long getTotalCount()
This is pre-calculated, so calling this operation occurs no computational expense.
public Histogram cropRemoveSmallerValues(long maxCount)
Histogram
reusing the bins in the current histogram, but with an upper
limit on the total count.
If more total count exists than maxCount
, values are removed in ascending
order, until the count is under the limit.
maxCount
- the maximum allowable total-count for the extracted histogram.Histogram
either a copy of the existing (if the total count
is less than maxCount
or cropped as per above rules.public Histogram cropRemoveLargerValues(long maxCount)
cropRemoveSmallerValues(long)
but larger values are removed rather than smaller
values if the total count is too high.maxCount
- the maximum allowable total-count for the extracted histogram.Histogram
either a copy of the existing (if the total count
is less than maxCount
or cropped as per above rules.public double mean(double power) throws OperationFailedException
Specifically, it calculates the mean of countFor(value) * value^power
across all
values.
power
- the power to raise each value to.OperationFailedException
- if the histogram has no values.public double mean(double power, double subtractValue) throws OperationFailedException
mean(double)
but a value may be subtracted before raising to a power.
Specifically, it calculates the mean of countFor(value) * (value -
subtractValue)^power
across all values.
power
- the power to raise each value to (after subtraction).subtractValue
- a value subtracted before raising to a power.OperationFailedException
- if the histogram has no values.public void iterateValues(Histogram.BinConsumer consumer)
consumer
for every value, increasing from min to max.consumer
- called for every bin.public void iterateValuesUntil(int limit, Histogram.BinConsumer consumer)
consumer
for every value until a limit, increasing from min to limit
.limit
- the maximum-value to consume (inclusive).consumer
- called for every bin.public int getMaxValue()
Copyright © 2010–2023 Owen Feehan, ETH Zurich, University of Zurich, Hoffmann-La Roche. All rights reserved.