/ 
CXC-Number-0.13
River stage zero No dependents
/ lib/CXC/Number/Sequence/Linear.pm-keep

NAME

Math::Histo::Bin::Linear - linear histogram binning

SYNOPSIS

  use Math::Histo::Grid::Linear;

$bin = Math::Histo::Bin::Linear->new( %options );

DESCRIPTION

Math::Histo::Bin::Linear constructs a self-consistent specification for grouping data in contiguous linear bins.

It can handle a range of specificity in the input binning scheme. For example,

  • The caller may specify the number of bins, the size of the bins, both, or none

  • Bins may be aligned so that a bin edge or the center of a bin falls upon a specified value.

  • The caller may specify a data range as either extrema or as a center and range_width.

Bin specifications

The two aspects of creating the binning scheme are

  1. Determining the range of data to bin. The range may be explicitly specified or derived from data limits. Range extrema derived from data are "softer" than those explicitly specified, in that they may be relaxed to better fit a grid onto the range.

  2. Fixing a grid onto the range. This may involve adjusting bin widths or the number of bins so that the range is fully covered by the grid. In addition, a grid may be anchored so that the beginning and ending bin edges fall upon certain values or so that bins are aligned so that a specific value falls on an edge or center of a bin.

Range specification

There are multiple ways to specify the range. Depending on how the grid is specified the final range may be slightly different from that requested (e.g., if a bin width is specified there may not be an integral number of bins in the range).

The acceptable parameter combinations and their resulting ranges are:

min, max => [ min, max )
min, range_width => [ min, min + range_width )
max, range_width => [ max - range_width, max )
center, range_width => [ center - range_width / 2, center + range_width / 2 )

The lower and upper edges of the grid are anchored to the range extrema if nbins is specified.

min, data_max => [ min, data_max ).

The lower most bin's lower edge is anchored to min if nbins is specified.

max, data_min => [ data_min, max ).

The upper most bin's upper edge is anchored to max if nbins is specified.

center, nbins, binw => [ center - nbins * binw / 2, center + nbins * binw / 2 )
min, nbins, binw => [ min, min + nbins * binw )
max, nbins, binw => [ max - nbins * binw, max )

The lower and upper edges of the grid are anchored to the range extrema

If min and max are not specified data_min and data_max must be specified and will result in a (soft) range of [ data_min, data_max ).

Grid specification

The size, number, and location of the bins is determined by the following combination of parameters (see "Range specification" for specific interactions of nbins and binw with range setting)

nbins

The number of bins. If neither nbins nor binw are specified, nbins defaults to 100.

binw

The bin width.

align

This specifies an optional grid alignment. It specifies a fiducial location within the bin and a value which must fall upon the fiducial location if the grid were extended to that value.

The alignment is specified as either a value or as an arrayref whose first element is the location, the second the value:

value
[ edge => value ]
[ center => value ]

In the first form the fiducial location defaults to edge.

center

Specify the center of the grid. If specified with nbins or binw and nothing else, this implicitly specifies an align attribute of

[ center => ( I<data_min> + I<data_max> ) / 2 ]

Range Adjustment

The range extrema may be adjusted from those specified if a grid alignment is specified via align (either explicitly or implicitly) or a bin width is specified which would lead to the extrema not falling upon bin edges.

The following scenarios are possible:

center is specified with no hard limits

The grid is extended about the specified center. The specified center value falls on the center of a bin unless align is used to specify another alignment.

INTERFACE

new
$bin = Math::Histo::Bin::Linear->new( %attr );

Construct a linear binning specification. The available attributes are:

min
max
center
range_width
binw
nbins
data_bounds
align

DIAGNOSTICS

Error message here, perhaps with %s placeholders

[Description of error here]

Another error message here

[Description of error here]

[Et cetera, et cetera]

CONFIGURATION AND ENVIRONMENT

Math::Histo::Grid::Linear requires no configuration files or environment variables.

DEPENDENCIES

None.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-math-histo-grid-linear@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Math-Histo-Grid.

SEE ALSO

VERSION

Version 0.01

LICENSE AND COPYRIGHT

Copyright (c) 2012 The Smithsonian Astrophysical Observatory

Math::Histo::Grid::Linear is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

AUTHOR

Diab Jerius <djerius@cpan.org>