|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectbb.science.Bins
public class Bins
Samples
, this class places no restriction on the values except that they must be normal (non-NaN and non-infinite).
This restriction means that the results returned by getBounds
, getBoundsMid
, and getPdf
may be safely supplied to other classes (e.g. the statistical routines inside Math2
).
This class almost always uses the following closed-open bin interval convention:
each is of the form [x0, x1)
,
that is, it includes all values x
that satisfy x0 <= x < x1
.
So, the left boundary is included inside the interval, but the right boundary is not.
The sole exception is the rightmost (largest) interval: it is a fully closed interval of the form [x0, x1]
.
Reason: one way to specify bin intervals is by supplying the min and max values that should be covered by the intervals,
and users will want that max value to occur inside an interval that includes more points than just that single max value.
For example, suppose the user is generating histograms of percents, and they want 10 bins to cover the range [0, 100]
.
Then with the interval scheme just described, the 10 intervals in this case will be
[0, 10), [10, 20), [20, 30), [30, 40), [40, 50), [50, 60), [60, 70), [70, 80), [80, 90), [90, 100]
.
This class always use a finite set of contiguous intervals.
These can be written, in order, as [x0, x1), [x1, x2), [x2, x3), ..., [xN-1, xN]
where N
is the total number of intervals.
A simplifying convention when speaking of contiguous intervals is to only list the beginning of each interval,
since each bin's end is the beginning of the subsequent bin.
Thus, we designate the previous set of intervals as {x0, x1, x2, ..., xN-1}
.
This is the format of bin interval boundary points that is returned by getBounds
.
Note that because the intervals are always equally sized,
{x0, x1, x2, ..., xN-1}
is equivalent to {x0, x0 + width, x0 + 2*width), ..., x0 + (N - 1)*width}
.
Nested Class Summary | |
---|---|
static class |
Bins.Intervals
Specifies how a given set of intervals are laid out. |
static class |
Bins.UnitTest
See the Overview page of the project's javadocs for a general description of this unit test class. |
Field Summary | |
---|---|
private double[] |
bounds
|
private long[] |
counts
|
private Bins.Intervals |
intervals
|
Constructor Summary | |
---|---|
private |
Bins(double[] values,
Bins.Intervals intervals)
Returns . |
|
Bins(double[] values,
double offset,
double width)
Returns . |
|
Bins(double[] values,
double begin,
double end,
int numberIntervals)
Returns . |
|
Bins(double[] values,
int numberIntervals)
Returns . |
Method Summary | |
---|---|
double[] |
getBounds()
Accessor for bounds . |
double[] |
getBoundsMid()
Returns the bin interval midpoints, that is, the points that are in the middle of each interval. |
long[] |
getCounts()
Accessor for counts . |
long |
getCountTotal()
Returns the total count, that is, the sum of all the elements of counts . |
Bins.Intervals |
getIntervals()
Accessor for intervals . |
double |
getIntervalWidth()
Accessor for intervals.width . |
double[] |
getPdf()
Returns the probability density function (PDF) that is approximated by the bins. |
String |
toString()
|
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
private final Bins.Intervals intervals
private final double[] bounds
private final long[] counts
Constructor Detail |
---|
public Bins(double[] values, double offset, double width) throws IllegalArgumentException, IllegalStateException
this
( values, Intervals.make
(values, offset, width) )
.
IllegalArgumentException
- if values == null; values.length == 0; any element of values is NaN;
offset is not normal
;
width is not normal and positive
IllegalStateException
- if some internal problem occurspublic Bins(double[] values, int numberIntervals) throws IllegalArgumentException, IllegalStateException
this
( values, Intervals.make
(values, numberIntervals) )
.
IllegalArgumentException
- if values == null; values.length == 0; any element of values is NaN;
numberIntervals <= 0
IllegalStateException
public Bins(double[] values, double begin, double end, int numberIntervals) throws IllegalArgumentException, IllegalStateException
this
( values, new Intervals
(begin, end, numberIntervals) )
.
IllegalArgumentException
- if begin is not normal
;
end is not normal;
begin is not < end;
numberIntervals <= 0
IllegalStateException
private Bins(double[] values, Bins.Intervals intervals) throws IllegalArgumentException
this
( values, new Intervals
(begin, end, numberIntervals) )
.
IllegalArgumentException
- if values or intervals is null;
any element of values falls outside the range [begin, end]Method Detail |
---|
public String toString()
toString
in class Object
public Bins.Intervals getIntervals()
intervals
.
public double[] getBounds()
bounds
.
Warning: the field is directly returned, not a copy, so mutating the result invalidates this instance. So, only mutate the result if this instance will no longer be used.
public long[] getCounts()
counts
.
Warning: the field is directly returned, not a copy, so mutating the result invalidates this instance. So, only mutate the result if this instance will no longer be used.
public double getIntervalWidth()
intervals.width
.
public double[] getBoundsMid()
This method is useful if the user wishes to characterize each bin interval by its middle point instead of left boundary.
public long getCountTotal()
counts
.
public double[] getPdf()
(count / n) / width
.
Here, n
is the total number of stored values (i.e. getCountTotal
)
(so count / n
converts the bin count to a probabilty)
and width is the bin interval's
width
(so / width
converts the probability into a probability density).
One reason why the PDF is useful is that, when sufficiently many values have been added the bins, the PDF curve becomes approximately independent both of the number of stored values and of the bin width, assuming that the values are drawn from a stable distribution.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |