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

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

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

BUGS

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.

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