edu.unh.sdb.datasource
Class AxisOrdering

java.lang.Object
  edu.unh.sdb.datasource.AxisOrdering

All Implemented Interfaces:

java.lang.Cloneable

public class AxisOrdering
extends java.lang.Object
implements java.lang.Cloneable

The AxisOrdering class is used to specify the axisOrdering of axes. Such orderings are used when a PhysicalDataSource or DataBlock maps an IndexSpaceID of arbitrary dimensionality to the 1D offset space of a file or array. They are also used by ISIterator to determine the order of the iteration. An axisOrdering is a tuple of distinct integers in the range 0..d-1, where d is the number of elements in the tuple. Of course, d is also the dimensionality of the axisOrdering. For example, an axisOrdering with 3 elements (A 3-D axisOrdering) must contain the integers 0,1, and 2 in some arbitrary order. If an axisOrdering is of the form {0,1,2...,d-1} where the elements are in strictly ascending order, then the axisOrdering is a default axisOrdering for d dimensions. Conceptually, an AxisOrdering is a list of axes (dimensions) in which the position of the axes in the list denotes how the data is composed into rows, columns, planes, etc. The axes are listed in order of decreasing significance. For example, the default axisOrdering for a 3D dataset is {0,1,2}. If we take axis 0 to indicate planes, axis 1 to indicate rows, and axis 2 to indicate columns, then the default axisOrdering indicates that planes are composed of rows, which are in turn composed of columns. Another way of looking at this is to say that the column axis changes most rapidly, followed by the row axis, and followed finally by the plane axis. If we instantiate an iterator with this axisOrdering and traverse a 3x2x4 space, we will visit the data in the following order:

(plane 0)       0  1  2  3
                4  5  6  7
        
(plane 1)       8  9  10 11
                12 13 14 15
        
(plane 2)       16 17 18 19 
                20 21 22 23

The other important use for AxisOrderings is to specify the mapping between the 1D space of an array or data file, and the n-D space of a DataSource or DataBlock. This is closely related to the way AxisOrderings work with traversals in that populating an n-D space with data from a 1D source can conceptually be done by traversing the space and placing each consecutive value from the 1D source into each position of the n-D index space as it is visited. For example, if a file containing the integers 0 through 23 in sorted order were read into a 3x2x4 array using a {0,1,2} axisOrdering, the diagram above would correspond to the result.

Field Summary

protected int[]

ordering

Constructor Summary

AxisOrdering(int size)
Creates an AxisOrdering of the specified size and populates it with the default axisOrdering: 0..size-1

AxisOrdering(int[] ordering)
Creates an AxisOrdering from the array of integers.

Method Summary

java.lang.Object	clone() Returns a copy of this AxisOrdering.
void	computeCoords(long offset, int[] coords, int[] axisWeights) Deprecated. in favor of the version with long axisWeights
void	computeCoords(long offset, int[] coords, long[] axisWeights) Compute the coordinates corresponding to the offset using the given axisWeights.
static long	computeOffset(IndexSpaceID dsid, long[] axisWeights) Map the IndexSpaceID to a single integer that serves as as an offset into the physical file or network source.
static long	computeOffset(int[] coords, long[] axisWeights) Map the coordinates array to a single integer that serves as as an offset into the physical file or network source.
AxisOrdering	copy() Returns a copy of this AxisOrdering.
int	dim() Returns the length (number of dimensions) of the axisOrdering.
int	getAxis(int index) Return the axis number stored at the given index.
int	getLeastSignificantAxis() Returns the least significant axis for this axisOrdering.
int	getMostSignificantAxis() Returns the most significant axis for this axisOrdering.
int	getNthLeastSignificantAxis(int n) Returns the Nth least significant axis for this axisOrdering, counting from zero.
static void	main(java.lang.String[] args)
long[]	makeAxisWeights(IndexSpaceID dimensionsID) Returns an array of axis weights corresponding to the axisOrdering and thedimensions parameter.
long[]	makeAxisWeights(int[] dimensions) Returns an array of axis weights corresponding to the axisOrdering and the dimensions parameter.
long[]	makeAxisWeights(ISBounds bounds) Returns an array of axis weights corresponding to the axisOrdering and bounds parameter.
long[]	makeAxisWeights(long[] dimensions) Returns an array of axis weights corresponding to the axisOrdering and the dimensions parameter.
void	setLeastSignificantAxis(int axis) Sets the Least Significant Axis to the given value by swapping the prior position of the argument axis with the prior Least Significant Axis.
void	setMostSignificantAxis(int axis) Chnages this axisOrdering so that the Most Significant Axis is the axis specified by the argument by swapping the prior position of the argument axis with the prior Most Significant Axis.
java.lang.String	toString() Return a String representing the object.
java.lang.String	toString(java.lang.String indent) Return a String representing the object indented by the argument string.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ordering

protected int[] ordering

Constructor Detail

AxisOrdering

public AxisOrdering(int size)

Creates an AxisOrdering of the specified size and populates it with the default axisOrdering: 0..size-1

AxisOrdering

public AxisOrdering(int[] ordering)

Creates an AxisOrdering from the array of integers.

Method Detail

setLeastSignificantAxis

public void setLeastSignificantAxis(int axis)

Sets the Least Significant Axis to the given value by swapping the prior position of the argument axis with the prior Least Significant Axis.

setMostSignificantAxis

public void setMostSignificantAxis(int axis)

Chnages this axisOrdering so that the Most Significant Axis is the axis specified by the argument by swapping the prior position of the argument axis with the prior Most Significant Axis.

makeAxisWeights

public long[] makeAxisWeights(ISBounds bounds)

Returns an array of axis weights corresponding to the axisOrdering and bounds parameter. The axisWeights array contains multipliers or "weights" for the axes. These weights are used in mapping an n-D space to a 1D space such as an array or file.The bounds parameter denotes the shape of the n-D space. For any IndexSpaceID, the dot product of the axis values and the axis weights is the offset of the ID in a 1D space such as a file or array. Taken individually, the axis weight for a dimension tells us the size of the 1D "step" between elements in the n-D space that are adjacent along the dimension. The bounds argument and this AxisOrdering should have the same dimensionality. If the bounds dimensionality is greater, extra dimensions are ignored. If shorter, an error is created.

makeAxisWeights

public long[] makeAxisWeights(IndexSpaceID dimensionsID)

Returns an array of axis weights corresponding to the axisOrdering and thedimensions parameter. The axisWeights array contains multipliers or "weights" for the axes. These weights are used in mapping an n-D space to a 1D space such as an array or file. The dimensions parameter denotes the shape of the n-D space. For any IndexSpaceID, the dot product of the axis values and the axis weights is the offset of the ID in a 1D space such as a file or array. Taken individually, the axis weight for a dimension tells us the size of the 1D "step" between elements in the n-D space that are adjacent along the dimension. The IndexSpaceID argument and this AxisOrdering should have the same dimensionality. If the IndexSpaceID dimensionality is greater, extra dimensions are ignored. If shorter, an error is created.

makeAxisWeights

public long[] makeAxisWeights(int[] dimensions)

Returns an array of axis weights corresponding to the axisOrdering and the dimensions parameter. The axisWeights array contains multipliers or "weights" for the axes. These weights are used in mapping an n-D space to a 1D space such as an array or file. The dimensions parameter denotes the shape of the n-D space. For any IndexSpaceID, the dot product of the axis values and the axis weights is the offset of the ID in a 1D space such as a file or array. Taken individually, the axis weight for a dimension tells us the size of the 1D "step" between elements in the n-D space that are adjacent along the dimension. The length of the array argument and the dimensinaloty of this AxisOrdering should match. If the array length is greater, extra dimensions are ignored. If shorter, an error is created.

makeAxisWeights

public long[] makeAxisWeights(long[] dimensions)

Returns an array of axis weights corresponding to the axisOrdering and the dimensions parameter. This version returns an array of long ints. The axisWeights array contains multipliers or "weights" for the axes. These weights are used in mapping an n-D space to a 1D space such as an array or file. The dimensions parameter denotes the shape of the n-D space. For any IndexSpaceID, the dot product of the axis values and the axis weights is the offset of the ID in a 1D space such as a file or array. Taken individually, the axis weight for a dimension tells us the size of the 1D "step" between elements in the n-D space that are adjacent along the dimension. The length of the array argument and the dimensinaloty of this AxisOrdering should match. If the array length is greater, extra dimensions are ignored. If shorter, an error is created.

computeOffset

public static final long computeOffset(IndexSpaceID dsid,
                                       long[] axisWeights)

Map the IndexSpaceID to a single integer that serves as as an offset into the physical file or network source. The second argument should be an array of axis weights computed the makeAxisWeights() method of this class. The dimensionality of the ISID and the length of the axisWeights argument should match. If the ISID dimensionality is smaller than the axisWeights length, an error will be created. If it is larger, extra dimensions will be ignored.

computeOffset

public static final long computeOffset(int[] coords,
                                       long[] axisWeights)

Map the coordinates array to a single integer that serves as as an offset into the physical file or network source. The second argument should be an array of axis weights computed the makeAxisWeights() method of this class. The lengths of the two arrays should match. If the coords array is shorter than the axisWeights array, an error will be created. If it is longer, extra dimensions will be ignored.

computeCoords

public final void computeCoords(long offset,
                                int[] coords,
                                int[] axisWeights)

Deprecated. in favor of the version with long axisWeights

Compute the coordinates corresponding to the offset using the given axisWeights. The lengths of the coords and axisWeights arguments should match. If coords is longer, extra elements are ignored. If coords is shorter, an error is created.

computeCoords

public final void computeCoords(long offset,
                                int[] coords,
                                long[] axisWeights)

Compute the coordinates corresponding to the offset using the given axisWeights. The lengths of the coords and axisWeights arguments should match. If coords is longer, extra elements are ignored. If coords is shorter, an error is created.

getAxis

public final int getAxis(int index)

Return the axis number stored at the given index.

dim

public final int dim()

Returns the length (number of dimensions) of the axisOrdering.

getLeastSignificantAxis

public final int getLeastSignificantAxis()

Returns the least significant axis for this axisOrdering. This axis is the one that changes most rapidly. This information is of particular use for BinaryFileDataSource, which is able to read a collection of datums lying along this dimension from the file in a single read operation.

getMostSignificantAxis

public final int getMostSignificantAxis()

Returns the most significant axis for this axisOrdering. This axis is the one that changes least rapidly.

getNthLeastSignificantAxis

public final int getNthLeastSignificantAxis(int n)

Returns the Nth least significant axis for this axisOrdering, counting from zero. For example, getNthLeastSignificantAxis(1) will return the axis that changes second most rapidly, while getNthLeastSignificantAxis(0) is equivalent to calling getLeastSignificantAxis().

copy

public final AxisOrdering copy()

Returns a copy of this AxisOrdering.

clone

public java.lang.Object clone()

Returns a copy of this AxisOrdering.

Overrides:

clone in class java.lang.Object

toString

public java.lang.String toString()

Return a String representing the object.

Overrides:

toString in class java.lang.Object

toString

public java.lang.String toString(java.lang.String indent)

Return a String representing the object indented by the argument string.

main

public static void main(java.lang.String[] args)