 NAME
 VERSION
 SYNOPSIS
 DESCRIPTION
 CONSTRUCTOR
 ATTRIBUTES
 METHODS
 SUBROUTINES
 BUGS
 SEE ALSO
 AUTHOR
 COPYRIGHT AND LICENSE
NAME
CXC::Number::Grid  A class representing a one dimensional numeric grid
VERSION
version 0.05
SYNOPSIS
$grid1 = CXC::Number::Grid>new( edges => [ 1, 2, 3 ] );
$grid2 = CXC::Number::Grid>new( edges => [ 4, 5, 6 ] );
$gridj = $grid1>join( $grid2 );
DESCRIPTION
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).
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.
CONSTRUCTOR
new
$grid = CXC::Number::Grid>new( \%args );
The constructor takes the following arguments:
edges
=> array of numbers or Math::BigFloat objects
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
=> array of Flags
An array of flags (
0
,1
), one per bin (not one per edge!), indicating whether the bin should be included when binning or not. oob
Boolean
If true,
"bin_edges"
will extend the grid by one bin at each end. The new lower bound isPOSIX::DBL_MAX
and the new upper bounds will bePOSIX::DBL_MAX
. This allows outofbounds data to be accumulated at the front and back of the grid.
ATTRIBUTES
oob
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.
edges
An array of ascending numbers which represent the edges of the bins in the grid.
include
An array of flags (0
, 1
), one per bin, indicating whether the bin should be included when binning or not.
METHODS
bin_edges
$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 outofbounds values if the "oob"
parameter is true. Extrema edges are set to POSIX::DBL_MAX
and POSIX::DBL_MAX
.
lb
$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 outofbounds bin values.
ub
$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 outofbounds bin values.
edges
$edges = $grid>edges;
Returns a reference to an array of Perl numbers which contains the edge values for the bins in the grid.
nedges
$nedges = $grid>nedges;
The number of bin edges.
nbins
$nbins = $grid>nbins;
The number of bins.
include
$include = $grid>include;
Returns a reference to an array of flags 0
, 1
, indicating whether a bin should be included in a process.
spacing
$spacing = $grid>spacing;
Returns a reference to an array of Perl numbers which contains the widths of each bin in the grid.
min
$min = $grid>min;
Returns the minimum bound of the grid as a Perl number.
max
$max = $grid>max;
Returns the maximum bound of the grid as a Perl number.
split
@grids = $grid>split;
Splits a grid on bins with an include value of 0
.
join
$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.
overlay
$grid = $grid1>overlay( $grid2, ..., $gridn, ?\%options );
Overlay one or more grids on top of $grid1
and return a new grid.
See "overlay_n"
for a description of the options.
bignum
$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
pdl
$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
SUBROUTINES
overlay_n
$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:
++
   
++
The result of overlay_n( $grid1, $grid2 )
is:
++
       
++
The %options
hash is optional; the following options are available:
snap_dist
=> float
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: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
tounderlay
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
tooverlay
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
join_n
$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.
The %options
hash is optional; the following options are available:
 gap => directive

What to do if the two grids do not exactly touch. The default is
include
.Available directives are:
shiftright

Translate the left grid until its maximum edge coincides with the right grid's minimum edge.
Before:
++ ++                   ++ ++
After:
+++                  +++
shiftleft

Translate the right grid until its minimum edge coincides with the let grid's maximum edge.
Before:
++ ++                   ++ ++
After:
+++                  +++
snapright

Set the left grid's maximum edge to the right grid's minimum edge.
Before:
++ ++                   ++ ++
After:
++                  ++
snapleft

Set the right grid's minimum edge to the left grid's maximum edge.
Before:
++ ++                   ++ ++
After:
++                  ++
snapboth

Set both the right grid's minimum edge and the left grid's maximum edge to the average of the two.
Before:
++ ++                   ++ ++
After:
++                  ++
include

Add a new bin
Before:
++ ++                   ++ ++
After:
++                   ++
exclude

Add a new bin, and mark it as being excluded
Before:
++ ++                   ++ ++
After:
++         X         ++
BUGS
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=CXCNumber or by email to bugcxcnumber@rt.cpan.org.
When submitting a bug or request, please include a testfile or a patch to an existing testfile that illustrates the bug or desired feature.
SEE ALSO
Please see those modules/websites for more information related to this module.
AUTHOR
Diab Jerius <djerius@cpan.org>
COPYRIGHT AND LICENSE
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