CXC::Number::Grid - A class representing a one dimensional numeric grid
version 0.12
$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.
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.
0
1
$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.
Specify either bounds or edges but not both.
bounds
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.
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
Instead of specifying the bin edges, the upper and lower bounds for each bin may be specified. If the supplied bins are not contiguous, interstitial bins will be created with an include flag of 0.
The bounds are specified as lower bound, upper bound pairs in the passed array, e.g.
[ $lb0, $ub0, $lb1, $ub1 ]
$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"
$flipped = $grid->not;
return a copy of $grid with a Boolean not of its include values.
$grid
$ABC = $A->or( $B, $C, ..., ?\%options );
Perform the logical OR of grids and return a new grid. See "or_n" for a description of the options.
"or_n"
$ABC = $A->and( $B, $C, ..., ?\%options );
Perform the logical AND of grids and return a new grid. See "and_n" for a description of the options.
"and_n"
$combined = $grid->combine_bins
Combine adjacent bins with the same include value.
For instance, a grid with the following construction:
edges => [ 0, 2, 4, 8, 12, 16 ] include => [ 0, 0, 1, 1, 0 ]
Would be combined into
edges => [ 0, 4, 12, 16 ] include => [ 0, 1, 0 ]
$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 ndarrays for the following methods
edges -> ndarray include -> ndarray bin_edges -> ndarray spacing -> ndarray lb -> ndarray ub -> ndarray
$string = $grid->to_string
Create a fairly readable string representation of the structure of a grid.
The logical NOT ! operator is overloaded; see "not" for details.
!
$AB = $A | $B
The logical OR ! operator is overloaded via
$AB = $A->or($B);
see "or" for details.
The logical AND & operator is overloaded via
&
$AB = $A->and($B);
$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, if
$overlay = overlay_n( $grid1, $grid2 );
with
$grid1: : +-------------------------------------------------+ : | | | | | | | | | | | : +-------------------------------------------------+ $grid2: : +--------------------------------+ : | | | | : +--------------------------------+ $overlay: : +-------------------------------------------------+ : | | | | | | | | : +-------------------------------------------------+
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).
$grid2
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.
Before: : +-----------------------+ +-----------------------+ : | | | | | | | | | | | | | | | | | | : +-----------------------+ +-----------------------+ After: : +-------------------------------------------------+ : | | | | | | | | | | | | | | | | | : +-------------------------------------------------+
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
Before: : +-----------------------+ +-----------------------+ : | | | | | | | | | | | | | | | | | | : +-----------------------+ +-----------------------+ After: : +-------------------------------------------------+ : | | | | | | | | | | | | | | | | | | : +-------------------------------------------------+
exclude
Add a new bin, and mark it as being excluded
Before: : +-----------------------+ +-----------------------+ : | | | | | | | | | | | | | | | | | | : +-----------------------+ +-----------------------+ After: : +-------------------------------------------------+ : | | | | | | | | |X| | | | | | | | | : +-------------------------------------------------+
$grid = CXC::Number::Grid::or_n( $grid1, $grid2, ..., $gridN, ?\%options );
Logical OR of grids based upon their include values. For example, given two grids:
Grid A: edges => [ 0, 2, 4, 8, 12, 16 ] include => [ 0, 1, 0, 1, 0 ] Grid B; edges => [ 0, 3, 6, 9, 10, 11, 16 ] include => [ 1, 0, 1, 0, 1, 0 ]
The result of
$A | $B
would be
edges => [ 0, 3, 4, 6, 9, 10, 11, 12, 16 ]; include => [ 1, 1, 0, 1, 1, 1, 1, 0 ];
The "oob" option for the returned grid is set to the default value.
$grid = CXC::Number::Grid::and_n( $grid1, $grid2, ..., $gridN, ?\%options );
Logical AND of grids based upon their include values. For example, given two grids:
Grid A: edges => [ 0, 2, 4, 8, 10, 16, 18 ] include => [ 0, 1, 0, 1, 0, 1 ] Grid B; edges => [ 1, 3, 6, 9, 10, 11, 16 ] include => [ 1, 0, 1, 0, 1, 0 ]
$A & $B
edges => [ 0, 1, 2, 3, 4, 6, 8, 9, 10, 11, 16, 18 ]; include => [ 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0 ];
This is called by MooX::Tag::TO_HASH to modify the generated hash representation.
This routine makes copies of the structures so that the hash can be modified without affecting the parent object.
Please report any bugs or feature requests to bug-cxc-number@rt.cpan.org or through the web interface at: https://rt.cpan.org/Public/Dist/Display.html?Name=CXC-Number
Source is available at
https://gitlab.com/djerius/cxc-number
and may be cloned from
https://gitlab.com/djerius/cxc-number.git
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.