CXC::Number::Grid - A class representing a one dimensional numeric grid
version 0.05
$grid1 = CXC::Number::Grid->new( edges => [ 1, 2, 3 ] ); $grid2 = CXC::Number::Grid->new( edges => [ 4, 5, 6 ] ); $gridj = $grid1->join( $grid2 );
CXC::Number::Grid provides an abstraction of a one dimensional grid. A grid is composed of contiguous bins, each of which has a flag indicating whether or not it should be included in a process (where process is defined by the user of the grid).
CXC::Number::Grid
This class provides facilities to join grids (e.g. butt them together) and overlay grids, with a number of approaches to handle the consequences of inevitable numeric imprecision.
Underneath the grid is stored as Math::BigFloat objects.
$grid = CXC::Number::Grid->new( \%args );
The constructor takes the following arguments:
edges
The bin edges in the grid. Will be converted to Math::BigFloat objects if they're not already. These must be in ascending order.
include
An array of flags (0, 1), one per bin (not one per edge!), indicating whether the bin should be included when binning or not.
0
1
oob
If true, "bin_edges" will extend the grid by one bin at each end. The new lower bound is -POSIX::DBL_MAX and the new upper bounds will be POSIX::DBL_MAX. This allows out-of-bounds data to be accumulated at the front and back of the grid.
"bin_edges"
-POSIX::DBL_MAX
POSIX::DBL_MAX
A boolean, which, if true, indicates that extra bins are added to either end of the grid which catch values outside of the range of the grid.
An array of ascending numbers which represent the edges of the bins in the grid.
An array of flags (0, 1), one per bin, indicating whether the bin should be included when binning or not.
$bin_edges = $grid->bin_edges;
Return the bin edges which should be used for binning as an array of Perl numbers. This differs from "edges" in that this includes the extra bins required to collect out-of-bounds values if the "oob" parameter is true. Extrema edges are set to -POSIX::DBL_MAX and POSIX::DBL_MAX.
"edges"
"oob"
$lb = $grid->lb;
Returns a reference to an array of Perl numbers which contains the lower bound values for the bins in the grid. This does not return out-of-bounds bin values.
$ub = $grid->ub;
Returns a reference to an array of Perl numbers which contains the upper bound values for the bins in the grid. This does not return out-of-bounds bin values.
$edges = $grid->edges;
Returns a reference to an array of Perl numbers which contains the edge values for the bins in the grid.
$nedges = $grid->nedges;
The number of bin edges.
$nbins = $grid->nbins;
The number of bins.
$include = $grid->include;
Returns a reference to an array of flags 0, 1, indicating whether a bin should be included in a process.
$spacing = $grid->spacing;
Returns a reference to an array of Perl numbers which contains the widths of each bin in the grid.
$min = $grid->min;
Returns the minimum bound of the grid as a Perl number.
$max = $grid->max;
Returns the maximum bound of the grid as a Perl number.
@grids = $grid->split;
Splits a grid on bins with an include value of 0.
$grid = $grid1->join( $grid2, $grid3, ..., ?\%options );
Join two grids together. This is akin to a butt joint, with control over how to handle any gap between the grids.
See "join_n" for a description of the options.
"join_n"
$grid = $grid1->overlay( $grid2, ..., $gridn, ?\%options );
Overlay one or more grids on top of $grid1 and return a new grid.
$grid1
See "overlay_n" for a description of the options.
"overlay_n"
$bin_edges = $grid->bignum->bin_edges;
Returns an object which returns copies of the internal Math::BigFloat objects for the following methods
edges -> Array[Math::BigFloat] bin_edges -> Array[Math::BigFloat] spacing -> Array[Math::BigFloat] lb -> Array[Math::BigFloat] ub -> Array[Math::BigFloat] min -> Math::BigFloat max -> Math::BigFloat
$bin_edges = $grid->pdl->bin_edges;
Returns an object which returns piddles for the following methods
edges -> piddle bin_edges -> piddle spacing -> piddle lb -> piddle ub -> piddle
$grid = CXC::Number::Grid::overlay_n( $grid1, $grid2, ... $gridN, ?\%options );
Overlay each successive grid on the overlay of the previous sequence of grids. The process essentially excises the range in the underlying grid covered by the overlying grid and inserts the overlying grid in that place. For example,
$grid1 is the underlying grid,
+-------------------------------------------------+ | | | | | | | | | | | +-------------------------------------------------+
and $grid2 is the grid which will be overlayed:
$grid2
+--------------------------------+ | | | | +--------------------------------+
The result of overlay_n( $grid1, $grid2 ) is:
overlay_n( $grid1, $grid2 )
+-------------------------------------------------+ | | | | | | | | +-------------------------------------------------+
The %options hash is optional; the following options are available:
%options
snap_dist
If the minimum or maximum edge of an overlying grid is closer than this number to the nearest unobscured edge in the underlying grid, snap the grid edges according to the value of snap_to.
The default value is 0, which turns off snapping.
snap_to
underlay
overlay
This indicates how to treat bin edges when "snap_dist" is not zero. From the above example of the overlay of two grids:
"snap_dist"
0 1 2 3 4 5 6 7 +-------------------------------------------------+ | | | | | | | | +-------------------------------------------------+ 1 1 2 2 2 2 1 1
The upper numbers are the edge indices and the lower indicate the grid the edge came from.
Note how close edges 1 and 2 are. Imagine that they are actually supposed to be the same, but numerical imprecision is at play.
Setting snap_to to underlay will adjust edge 2 (which originates from $grid2, the overlying grid) so that it is equal to edge 1 (from $grid1, the underlying grid).
0 1 2 3 4 5 6 +-------------------------------------------------+ | | | | | | | +-------------------------------------------------+ 1 1 2 2 2 1 1
Conversely, setting snap_to to overlay will adjust edge 1 (originating from $grid1, the underlying grid) so that it is equal to edge 2 (from $grid2 the overlying grid).
0 1 2 3 4 5 6 +-------------------------------------------------+ | | | | | | | +-------------------------------------------------+ 1 2 2 2 2 1 1
$grid = CXC::Number::Grid::join_n( $grid1, $grid2, ..., $gridN, ?\%options );
Join one or more grids. This is akin to a butt joint, with control over how to handle any gap between the grids.
While normally grids should not overlap, up to one overlapping bin is allowed in order to accommodate numerical imprecision. The "gap" option determines how to handle overlaps or gap.
"gap"
What to do if the two grids do not exactly touch. The default is include.
Available directives are:
shift-right
Translate the left grid until its maximum edge coincides with the right grid's minimum edge.
Before:
+-----------------------+ +-----------------------+ | | | | | | | | | | | | | | | | | | +-----------------------+ +-----------------------+
After:
+-----------------------+-----------------------+ | | | | | | | | | | | | | | | | | +-----------------------+-----------------------+
shift-left
Translate the right grid until its minimum edge coincides with the let grid's maximum edge.
snap-right
Set the left grid's maximum edge to the right grid's minimum edge.
+-------------------------------------------------+ | | | | | | | | | | | | | | | | | +-------------------------------------------------+
snap-left
Set the right grid's minimum edge to the left grid's maximum edge.
snap-both
Set both the right grid's minimum edge and the left grid's maximum edge to the average of the two.
Add a new bin
+-------------------------------------------------+ | | | | | | | | | | | | | | | | | | +-------------------------------------------------+
exclude
Add a new bin, and mark it as being excluded
+-------------------------------------------------+ | | | | | | | | |X| | | | | | | | | +-------------------------------------------------+
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=CXC-Number or by email to bug-cxc-number@rt.cpan.org.
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
Please see those modules/websites for more information related to this module.
CXC::Number
CXC::Number::Sequence
Diab Jerius <djerius@cpan.org>
This software is Copyright (c) 2019 by Smithsonian Astrophysical Observatory.
This is free software, licensed under:
The GNU General Public License, Version 3, June 2007
To install CXC::Number, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CXC::Number
CPAN shell
perl -MCPAN -e shell install CXC::Number
For more information on module installation, please visit the detailed CPAN module installation guide.