/ 
CXC-Number-0.13
River stage zero No dependents
/ CXC::Number::Grid

NAME

CXC::Number::Grid - A class representing a one dimensional numeric grid

VERSION

version 0.13

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.

OBJECT 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.

CONSTRUCTORS

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.

Specify either bounds or edges but not both.

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 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.

bounds => array of numbers or Math::BigFloat objects

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 ]

Specify either bounds or edges but not both.

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 out-of-bounds 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 out-of-bounds 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 out-of-bounds 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.

not

$flipped = $grid->not;

return a copy of $grid with a Boolean not of its include values.

or

$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.

and

$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.

combine_bins

$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 ]

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 ndarrays for the following methods

edges     -> ndarray
include   -> ndarray
bin_edges -> ndarray
spacing   -> ndarray
lb        -> ndarray
ub        -> ndarray

to_string

$string = $grid->to_string

Create a fairly readable string representation of the structure of a grid.

OVERLOAD

!

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.

&

$AB = $A | $B

The logical AND & operator is overloaded via

$AB = $A->and($B);

see "or" for details.

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, if

$overlay = overlay_n( $grid1, $grid2 );

with

$grid1:
:     +-------------------------------------------------+
:     |    |    |    |    |    |    |    |    |    |    |
:     +-------------------------------------------------+
$grid2:
:            +--------------------------------+
:            |          |         |           |
:            +--------------------------------+
$overlay:
:     +-------------------------------------------------+
:     |    | |          |         |           |    |    |
:     +-------------------------------------------------+

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 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

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:

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.

Before:
:  +-----------------------+ +-----------------------+
:  |  |  |  |  |  |  |  |  | |  |  |  |  |  |  |  |  |
:  +-----------------------+ +-----------------------+
After:
:  +-----------------------+-----------------------+
:  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
:  +-----------------------+-----------------------+
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.

Before:
:  +-----------------------+ +-----------------------+
:  |  |  |  |  |  |  |  |  | |  |  |  |  |  |  |  |  |
:  +-----------------------+ +-----------------------+
After:
:  +-------------------------------------------------+
:  |  |  |  |  |  |  |  |  |    |  |  |  |  |  |  |  |
:  +-------------------------------------------------+
snap-both

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|  |  |  |  |  |  |  |  |
:  +-------------------------------------------------+

or_n

$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.

and_n

$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 ]

The result of

$A & $B

would be

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 ];

The "oob" option for the returned grid is set to the default value.

INTERNALS

Methods

_modify_hashr

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.

SUPPORT

Bugs

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

Source is available at

https://gitlab.com/djerius/cxc-number

and may be cloned from

https://gitlab.com/djerius/cxc-number.git

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