grig.tree package

Submodules

grig.tree.base_tree module

class grig.tree.base_tree.BaseTree(argument, shape=None, build_type='all', leaf_size=40, large_data=False, **distance_kwargs)

Bases: object

Attributes:

balltree_initialized

Return True if the BallTree has been initialized.

features

Returns the number of features (dimensions) in the tree.

hood_initialized

Return True if the neighbourhood tree has been initialized.

n_blocks

Return the total number of blocks in the tree.

n_members

Return the total number of coordinates stored in the tree.

search

Return a search array used to identify neighbouring blocks.

shape

Return the shape of the coordinate bins of the tree.

Methods

__call__(x[, reverse])	Returns the block index of a coordinate
block_members(block[, get_locations])	Get block members from the neighborhood tree.
build_ball_tree_for_block(block)	Build a ball tree for a neighborhood around a single block.
build_tree(coordinates[, shape, method, ...])	Create the ball and hood tree structures from coordinates.
estimate_ball_tree_bytes(coordinates[, ...])	Estimate the maximum number of bytes used to construct the ball-tree.
estimate_hood_tree_bytes(coordinates[, window])	Estimate the maximum byte size for the neighborhood tree.
estimate_max_bytes(coordinates[, window, ...])	Estimate the maximum number of bytes required by the tree.
estimate_n_bins(coordinates[, window])	Estimate the number of bins in the hood tree.
estimate_split_tree_bytes(coordinates[, ...])	Return the size of a ball tree for a single neighborhood.
from_index(index)	Find the lower corner coordinate for a tree block index.
get_class_for(thing)	Return a Tree class specific to a given grid, resampler, or name.
get_class_for_name(name)	Return a Tree class of the given name.
hood_members(center_block[, get_locations])	Find all members within the neighborhood of a single block.
neighborhood(index[, cull, valid_neighbors])	Make a neighborhood from an input index.
query_radius(coordinates[, radius, block])	Return all tree members within a certain distance of given points.
to_index(coordinates)	Find the tree block indices of a coordinate or set of coordinates.

property balltree_initialized

Return True if the BallTree has been initialized.

Returns:

bool

block_members(block, get_locations=False)

Get block members from the neighborhood tree.

Parameters:

blocknp.ndarray of int

Block locations.

get_locationsbool, optional

If set, locations of members are also returned.

Returns:

membersnp.ndarray

Members of the block.

locationsnp.ndarray, optional

Locations of the members.

build_ball_tree_for_block(block)

Build a ball tree for a neighborhood around a single block.

Parameters:

blockint

The center block of the neighborhood.

Returns:

None

build_tree(coordinates, shape=None, method='all', leaf_size=40, **distance_kwargs)

Create the ball and hood tree structures from coordinates.

Populates the tree with coordinates.

Parameters:

coordinatesnumpy.ndarray (n_features, n_coordinates)

The coordinates from which to build the trees.

shapen-tuple of int, optional

The shape of the tree. If not supplied it is calculated as floor(max(coordinate[k])) + 1 for the feature k.

methodstr, optional

Specifies the trees to build. Available options are {‘hood’, ‘balltree’, ‘all’, None}. The default (‘all’) builds both the balltree and hood tree.

leaf_sizeint, optional

An specifies the point at which the ball tree switches over to the brute force method. See sklearn.neighbors.BallTree() for further information.

distance_kwargsdict, optional

Optional keyword arguments passed into sklearn.neighbors.DistanceMetric(). The default is to use the “minkowski” definition with p=2, i.e., the Euclidean definition.

Returns:

None

classmethod estimate_ball_tree_bytes(coordinates, leaf_size=40)

Estimate the maximum number of bytes used to construct the ball-tree.

According to sklearn documentation, the memory needed to store the tree scales as:

2 ** (1 + floor(log2((n-1) / leaf_size))) - 1

However, empirically the data also scale as (ndim+1) * leaf_size.

The estimated number of elements is given as:

(ndim+1) * leaf_size * (2 ** (1+floor(log2((n-1) / leaf_size)))-1)

This is then scaled by the number of bytes in a float (typically 8).

Parameters:

coordinatesnumpy.ndarray

The coordinates of shape (n_dimensions, n)

leaf_sizeint

The number of leaves used to construct the ball-tree

Returns:

max_sizeint

The maximum number of bytes used to construct the tree.

classmethod estimate_hood_tree_bytes(coordinates, window=1)

Estimate the maximum byte size for the neighborhood tree.

Parameters:

coordinatesnumpy.ndarray

The coordinates of shape (n_dimensions, n).

windowint or float or numpy.ndarray, optional

The window binning size. If a numpy array is supplied, it should be of shape (n_dimensions,).

Returns:

bytesint

classmethod estimate_max_bytes(coordinates, window=1, leaf_size=40, full_tree=True, **kwargs)

Estimate the maximum number of bytes required by the tree.

Parameters:

coordinatesnumpy.ndarray

The coordinates for the tree of shape (n_dimensions, n)

windowint or float, optional

The size of the tree windows

leaf_sizeint, optional

The number of leaves used to construct the ball-tree

full_treebool, optional

Calculate the maximum number of bytes if the full ball-tree is pre-calculated. Otherwise, calculates the size of a single neighborhood sized ball-tree.

kwargsdict, optional

Additional keyword arguments to pass that may be used by subclasses of the BaseTree.

Returns:

max_sizeint

The maximum number of bytes used to construct the tree.

classmethod estimate_n_bins(coordinates, window=1)

Estimate the number of bins in the hood tree.

Parameters:

coordinatesnumpy.ndarray

The coordinates of shape (n_dimensions, n).

windowint or float or numpy.ndarray, optional

The window binning size. If a numpy array is supplied, it should be of shape (n_dimensions,).

Returns:

bytesint

classmethod estimate_split_tree_bytes(coordinates, window=1, leaf_size=40)

Return the size of a ball tree for a single neighborhood.

Parameters:

coordinatesnumpy.ndarray

The coordinates of shape (n_dimensions, n)

windowint or float or numpy.ndarray, optional

The window binning size. If a numpy array is supplied, it should be of shape (n_dimensions,).

leaf_sizeint

The number of leaves used to construct the ball-tree

Returns:

max_sizeint

The maximum number of bytes used to construct the tree.

property features

Returns the number of features (dimensions) in the tree.

Returns:

int

from_index(index)

Find the lower corner coordinate for a tree block index.

Parameters:

indexint or numpy.ndarray (n_indices,)

The indices for which to return the lower corner coordinate(s).

Returns:

lower_corner_coordinatesnumpy.ndarray of int

An array of shape (n_features,) or (n_features, n_indices) containing the lower corner coordinates of supplied tree block indices.

Examples

The lower corner coordinate in a tree block is given as the floored values of all coordinates that exist inside the block. For example, the index 15 in a tree of shape (5, 6) corresponds to coordinates in the range x = (2->3), y = (3->4). Therefore, the lower coordinate is (2, 3).

static get_class_for(thing)

Return a Tree class specific to a given grid, resampler, or name.

Parameters:

thingBaseGrid or ResampleBase or str

Either a sub-class of a BaseGrid, ResampleBase, or a string.

Returns:

BaseTree subclass

static get_class_for_name(name)

Return a Tree class of the given name.

Parameters:

namestr

The name of the tree.

Returns:

BaseTree subclass

property hood_initialized

Return True if the neighbourhood tree has been initialized.

Returns:

bool

hood_members(center_block, get_locations=False)

Find all members within the neighborhood of a single block.

Parameters:

center_blockint

The index of the block at the center of the neighborhood.

get_locationsbool, optional

If True, return the coordinates of the hood members.

Returns:

members, [coordinates]

members is a numpy.ndarray of int and shape (found_members,). If get_locations was set to True, coordinates is of shape (n_features, found_members).

property n_blocks

Return the total number of blocks in the tree.

The total number of blocks is simply the number of available coordinate bins.

Returns:

int

property n_members

Return the total number of coordinates stored in the tree.

Returns:

int

neighborhood(index, cull=False, valid_neighbors=False)

Make a neighborhood from an input index.

Parameters:

indexint

The center index for the neighborhood.

cullbool, optional

If set, bad indices are dropped.

valid_neighborsbool, optional

If set, returns good locations as well as the neighborhood..

Returns:

hoodnp.ndarray of int

The tree block indices for the neighborhood.

keepnp.ndarray of bool, optional

Good indices in the neighborhood.

query_radius(coordinates, radius=1.0, block=None, **kwargs)

Return all tree members within a certain distance of given points.

Quickly retrieves all members of the tree population within the radius of some defined coordinate(s). The default distance definition is “minkowski” with p=2, which is equivalent to the “euclidean” definition. For a list of available distance metric please see sklearn.neighbors.BallTree.valid_metrics. The distance metric may be defined during PolynomialTree initialization.

Parameters:

coordinatesnumpy.ndarray

An (n_features, n_coordinates) or (n_features,) array containing coordinates around which to determine tree members within a certain radius.

radiusfloat, optional

The search radius around each coordinate.

blockint, optional

Used to create a temporary ball tree for the given block when operating on large data.

kwargsdict, optional

Keywords for sklearn.neighbors.BallTree.query_radius().

Returns:

indicesnumpy.ndarray of object (n_coordinates,)

Each element is a numpy integer array containing the indices of tree members within radius. This return value may change depending on the options in kwargs. Please see sklearn.neighbors.BallTree.query_radius() for further information.

property search

Return a search array used to identify neighbouring blocks.

Returns:

search_arraynumpy.ndarray (int)

An (n_features, n_permutations) containing values {-1, 0, 1} where each permutation gives a block offset in relation to a central block.

property shape

Return the shape of the coordinate bins of the tree.

The coordinate bins divide coordinates into bins where all values between 2 <= x_i < 3 for coordinate x in dimension i are in bin 0. Note that coordinates should have been scaled accordingly such that they range between 0 -> n, where n are the maximum number of bins.

Returns:

shapetuple (int)

The number of bins in each dimension.

to_index(coordinates)

Find the tree block indices of a coordinate or set of coordinates.

Parameters:

coordinatesnumpy.ndarray (n_feature,) or (n_feature, n_coordinates)

The coordinates for which to return tree block indices. Coordinates should be scaled such that they range from 0 -> tree.shape[k] for the feature k.

Returns:

index or indicesnp.int64 or np.ndarray (n_coordinates,)

The tree block indices for the supplied coordinates.

Examples

A tree of shape (5, 6) in 2 dimensions contains coordinates ranging from 0-5 in x, and 0-6 in y. The coordinate (x, y) = (2.7, 3.1) would exist in tree block [2, 3] (floored values), but the tree block structure is one-dimensional. The actual block index would be 15 since it is calculated as (2 * 6) + 3, or (x * shape[1]) + y.

grig.tree.kernel_tree module

class grig.tree.kernel_tree.KernelTree(argument, shape=None, build_type='all', leaf_size=40, kernel=None, kernel_spacing=1.0, kernel_offsets=None, smoothing=0.0, imperfect=False, degrees=3, large_data=False, spline_kwargs=None, **distance_kwargs)

Bases: BaseTree

Attributes:

balltree_initialized

Return True if the BallTree has been initialized.

coefficients

Return the spline coefficients.

degrees

Return the degree of the spline fit.

exit_code

Return the spline exit code.

exit_message

Return the spline exit message.

extent

Return the extent of the kernel coordinates in each dimension.

features

Returns the number of features (dimensions) in the tree.

fit_valid

Return whether the spline successfully fit the provided kernel.

hood_initialized

Return True if the neighbourhood tree has been initialized.

knot_steps

Return the 1-D panel mapping steps for each dimension.

knots

Return the coordinates of the spline knots.

n_blocks

Return the total number of blocks in the tree.

n_knots

Return the number of spline knots in each dimension.

n_members

Return the total number of coordinates stored in the tree.

nk1

Return the nk1 values for the knots.

panel_mapping

Return the 1-D to N-D panel mapping used for subsequent fitting.

panel_steps

Return the 1-D panel mapping steps for each dimension.

resampling_arguments

Return the spline parameters necessary for resampling.

search

Return a search array used to identify neighbouring blocks.

shape

Return the shape of the coordinate bins of the tree.

smoothing

Return the spline smoothing factor.

spline_mapping

Return the 1-D to N-D index map for the spline.

Methods

__call__(x[, reverse])	Returns the block index of a coordinate
block_members(block[, get_locations])	Get block members from the neighborhood tree.
build_ball_tree_for_block(block)	Build a ball tree for a neighborhood around a single block.
build_tree(coordinates[, shape, method, ...])	Create the ball and hood tree structures from coordinates.
estimate_ball_tree_bytes(coordinates[, ...])	Estimate the maximum number of bytes used to construct the ball-tree.
estimate_hood_tree_bytes(coordinates[, window])	Estimate the maximum byte size for the neighborhood tree.
estimate_max_bytes(coordinates[, window, ...])	Estimate the maximum number of bytes required by the tree.
estimate_n_bins(coordinates[, window])	Estimate the number of bins in the hood tree.
estimate_split_tree_bytes(coordinates[, ...])	Return the size of a ball tree for a single neighborhood.
fit_spline([degrees, smoothing])	Fit a spline to the tree kernel.
from_index(index)	Find the lower corner coordinate for a tree block index.
get_class_for(thing)	Return a Tree class specific to a given grid, resampler, or name.
get_class_for_name(name)	Return a Tree class of the given name.
hood_members(center_block[, get_locations])	Find all members within the neighborhood of a single block.
neighborhood(index[, cull, valid_neighbors])	Make a neighborhood from an input index.
parse_kernel(kernel[, kernel_spacing, ...])	Check and then convert the kernel arguments for spline fitting.
query_radius(coordinates[, radius, block])	Return all tree members within a certain distance of given points.
set_kernel(kernel[, kernel_spacing, ...])	Setting the kernel automatically initializes a Spline object that is solved and may be used for interpolating kernel values at locations away from the kernel vertices.
to_index(coordinates)	Find the tree block indices of a coordinate or set of coordinates.

property coefficients

Return the spline coefficients.

Returns:

numpy.ndarray (float)

The spline coefficients of shape (n_coefficients,). Here, n_coefficients = product(n_knots - degrees - 1) over all dimensions.

property degrees

Return the degree of the spline fit.

Returns:

numpy.ndarray (int)

The spline degrees of shape (n_dimensions,) for each dimension in (x, y, z, …) order.

property exit_code

Return the spline exit code.

Please see Spline for further details on all codes.

Returns:

int

property exit_message

Return the spline exit message.

Please see Spline for further details on all codes.

Returns:

str

property extent

Return the extent of the kernel coordinates in each dimension.

Returns:

extentnumpy.ndarray (float)

An array of shape (n_dimensions, 2) where extent[0, 0] gives the minimum offset for dimension 0 and extent[0, 1] gives the maximum offset for dimension 0.

fit_spline(degrees=3, smoothing=0.0, **spline_kwargs)

Fit a spline to the tree kernel.

Parameters:

degreesint or numpy.ndarray (int), optional

The degree of spline to fit in each dimension. Either a scalar can be supplied pertaining to all dimensions, or an array of shape (n_dimensions,) can be used.

smoothingfloat, optional

Used to specify the smoothing factor. If set to None, the smoothing will be determined based on user settings or input data. If exact is True, smoothing will be disabled (zero). If exact is False, smoothing will be set to n - sqrt(2 * n) where n is the number of data values. For interpolation, smoothing should be set to zero. Smoothing must be >= 0.

spline_kwargsdict, optional

Please see Spline for a list of all spline initialization keyword arguments. Note that solve will always be set to True.

Returns:

None

Raises:

RuntimeError

If the fit to the kernel was not adequate for further fitting. If no further tweaking of the input parameters is possible, set imperfect`=`True during initialization, or manually set the imperfect attribute to True manually.

property fit_valid

Return whether the spline successfully fit the provided kernel.

If imperfect fits are permitted, will return True so long as a solution exists. In cases where imperfect fits are not allowed, the fit will only be considered valid if a full rank solution has been determine, or the fit was successful within the provided user or default parameters.

Returns:

validbool

True if the fit provides a valid solution, and False otherwise.

property knot_steps

Return the 1-D panel mapping steps for each dimension.

Returns:

numpy.ndarray (int)

The knot steps of shape (n_dimensions,)

property knots

Return the coordinates of the spline knots.

Returns:

numpy.ndarray (float)

An array of shape (n_dimensions, max(n_knots)).

property n_knots

Return the number of spline knots in each dimension.

Returns:

numpy.ndarray (int)

An array of shape (n_dimensions,).

property nk1

Return the nk1 values for the knots.

The returned value is n_knots - degrees - 1.

Returns:

numpy.ndarray (int)

The nk1 values of shape (n_dimensions,).

property panel_mapping

Return the 1-D to N-D panel mapping used for subsequent fitting.

Each panel is bounded by the knot vertices.

Returns:

numpy.ndarray (int)

The 1-D to N-D panel map of shape (n_dimensions, n_panels).

property panel_steps

Return the 1-D panel mapping steps for each dimension.

Returns:

numpy.ndarray (int)

The panel steps of shape (n_dimensions,)

parse_kernel(kernel, kernel_spacing=1.0, kernel_offsets=None)

Check and then convert the kernel arguments for spline fitting.

Parameters:

kernelnumpy.ndarray (float)

The kernel to set. Must have n_features dimensions.

kernel_spacingfloat or numpy.ndarray (float), optional

The spacing between each kernel element in units of the coordinates. Supply either as a single value for all features, or as an array of shape (n_features,) giving the kernel spacing for each feature.

kernel_offsetstuple or array_like, optional

If the kernel is regular, should be an n-dimensional tuple containing the grid indices in each dimension. Otherwise, should be an array of shape (n_dimensions, kernel.size).

Returns:

None

property resampling_arguments

Return the spline parameters necessary for resampling.

Returns all of the arguments in the correct order necessary for perform_fit() aside from the coordinates (the first argument).

Returns:

tuple

set_kernel(kernel, kernel_spacing=1.0, kernel_offsets=None, degrees=3, smoothing=0.0, imperfect=None, **spline_kwargs)

Setting the kernel automatically initializes a Spline object that is solved and may be used for interpolating kernel values at locations away from the kernel vertices. Both regular (grid) kernels and irregular kernels may be supplied. Either kernel_spacing or kernel_offsets must be supplied in order to determine the coordinates of any interpolated points. In the case of irregular kernels, these must be provided in kernel_offsets. For regularly spaced grid, kernel_spacing may be provided instead.

Generally, smoothing should be set to zero for interpolation. However, in cases where a noisy irregular kernel is provided, smoothing may be set to None for a nominal fit, or provided if an optimal value is known.

Parameters:

kernelnumpy.ndarray (float)

The kernel to set. Must have n_features dimensions.

kernel_spacingfloat or numpy.ndarray (float), optional

The spacing between each kernel element in units of the coordinates. Supply either as a single value for all features, or as an array of shape (n_features,) giving the kernel spacing for each feature.

kernel_offsetstuple or array_like, optional

If the kernel is regular, should be an n-dimensional tuple containing the grid indices in each dimension. Otherwise, should be an array of shape (n_dimensions, kernel.size).

degreesint or numpy.ndarray (int), optional

The degree of spline to fit in each dimension. Either a scalar can be supplied pertaining to all dimensions, or an array of shape (n_dimensions,) can be used.

smoothingfloat, optional

Used to specify the smoothing factor. If set to None, the smoothing will be determined based on user settings or input data. If exact is True, smoothing will be disabled (zero). If exact is False, smoothing will be set to n - sqrt(2 * n) where n is the number of data values. For interpolation, smoothing should be set to zero. Smoothing must be >= 0.

imperfectbool, optional

If a spline fit to the kernel is allowed to be imperfect (True), will only raise an error on spline fitting if a major error was encountered. Otherwise, fits will be permitted so long as a solution was reached, even if that solution did not meet expectations.

spline_kwargsdict, optional

Please see Spline for a list of all spline initialization keyword arguments. Note that solve will always be set to True.

Returns:

None

property smoothing

Return the spline smoothing factor.

Returns:

float

property spline_mapping

Return the 1-D to N-D index map for the spline.

Returns:

numpy.ndarray (int)

The spline map of shape (n_dimensions, product(degrees + 1)).

grig.tree.polynomial_tree module

class grig.tree.polynomial_tree.PolynomialTree(argument, shape=None, build_type='all', order=None, fix_order=True, leaf_size=40, large_data=False, **distance_kwargs)

Bases: BaseTree

Attributes:

balltree_initialized

Return True if the BallTree has been initialized.

derivative_term_map

Returns mapping necessary to describe the 1st derivative of the tree.

exponents

Return the polynomial exponents for the tree.

features

Returns the number of features (dimensions) in the tree.

hood_initialized

Return True if the neighbourhood tree has been initialized.

n_blocks

Return the total number of blocks in the tree.

n_members

Return the total number of coordinates stored in the tree.

order

Return the order of the polynomial for the tree.

order_symmetry

Return whether the orders are symmetrical.

order_varies

Return whether the order may be decreased.

phi_terms_precalculated

Return whether the polynomial terms have been calculated.

search

Return a search array used to identify neighbouring blocks.

shape

Return the shape of the coordinate bins of the tree.

Methods

__call__(x[, reverse])	Returns the block index of a coordinate
block_members(block[, get_locations, get_terms])	Find all members within a single block.
build_ball_tree_for_block(block)	Build a ball tree for a neighborhood around a single block.
build_tree(coordinates[, shape, method, ...])	Create the ball and hood tree structures from coordinates.
create_phi_terms_for([block])	Create the phi terms on demand.
estimate_ball_tree_bytes(coordinates[, ...])	Estimate the maximum number of bytes used to construct the ball-tree.
estimate_hood_tree_bytes(coordinates[, window])	Estimate the maximum byte size for the neighborhood tree.
estimate_max_bytes(coordinates[, window, ...])	Estimate the maximum number of bytes required by the tree.
estimate_n_bins(coordinates[, window])	Estimate the number of bins in the hood tree.
estimate_split_tree_bytes(coordinates[, ...])	Return the size of a ball tree for a single neighborhood.
from_index(index)	Find the lower corner coordinate for a tree block index.
get_class_for(thing)	Return a Tree class specific to a given grid, resampler, or name.
get_class_for_name(name)	Return a Tree class of the given name.
hood_members(center_block[, get_locations, ...])	Find all members within the neighborhood of a single block.
neighborhood(index[, cull, valid_neighbors])	Make a neighborhood from an input index.
precalculate_phi_terms()	Calculates polynomial terms for the tree coordinates and order.
query_radius(coordinates[, radius, block])	Return all tree members within a certain distance of given points.
set_order(order[, fix_order])	Set the order(s) of polynomial fit for the resampling algorithm tree.
to_index(coordinates)	Find the tree block indices of a coordinate or set of coordinates.

block_members(block, get_locations=False, get_terms=False)

Find all members within a single block.

Parameters:

blockint

The index of the block.

get_locationsbool, optional

If True, return the coordinates of the hood members.

get_termsbool, optional

If True, return the calculated “phi” terms of hood members. Note that a polynomial order must have been set, and terms calculated. See PolynomialTree.set_order(), and PolynomialTree.precalculate_phi_terms() for further information.

Returns:

members, [coordinates, terms]

members is a numpy.ndarray of int and shape (found_members,). If get_locations was set to True, coordinates is of shape (n_features, found_members). If get_terms was set to True, terms is of shape (n_terms, found_members).

create_phi_terms_for(block=None)

Create the phi terms on demand.

If block is None, creates the phi terms over all samples. Otherwise, creates phi terms for all samples in the neighborhood of block.

Parameters:

blockint, optional

The block for which to create the phi terms. If None is supplied, will calculate for all coordinates.

Returns:

hood_membersnumpy.ndarray (int) or slice or None

The samples within the neighborhood of block, all indices or None if not calculated.

property derivative_term_map

Returns mapping necessary to describe the 1st derivative of the tree.

The terms describing the derivative of a polynomial function should all be present in the exponent terms of the tree, but need to be reordered in a specific way and may also contain an additional coefficient. Once the coefficients of the fit are known (c), the derivative of feature k may be be calculated by:

sum(h[k, 0] * c[h[k, 1]] * p[h[k, 2], k])

where p are the exponent terms, and h is the map returned by this property.

Returns:

mappingnumpy.ndarray (int)

An array of shape (n_features, 3, n_terms).

classmethod estimate_max_bytes(coordinates, window=1, leaf_size=40, full_tree=True, order=2)

Estimate the maximum number of bytes required by the tree.

This includes pre-calculation of the phi terms for polynomial representation.

Parameters:

coordinatesnumpy.ndarray

The coordinates for the tree of shape (n_dimensions, n)

windowint or float, optional

The size of the tree windows

leaf_sizeint, optional

The number of leaves used to construct the ball-tree

full_treebool, optional

Calculate the maximum number of bytes if the full ball-tree is pre-calculated. Otherwise, calculates the size of a single neighborhood sized ball-tree.

orderint or numpy.ndarray (int), optional

The order of polynomial to fit as an integer for all dimensions or an array of shape (n_dimensions,).

Returns:

max_sizeint

An upper limit for the maximum number of bytes used to construct the tree.

property exponents

Return the polynomial exponents for the tree.

The polynomial exponents describe how the polynomial terms should be calculated. For example, the exponents [[0, 0], [1, 0], [2, 0], [0, 1], [1, 1], [0, 2]] represent the equation:

f(x, y) = c0 + c1.x + c2.x^2 + c3.y + c4.xy + c5.y^2

Returns:

numpy.ndarray (int)

An array of shape (n_exponents, n_features)

hood_members(center_block, get_locations=False, get_terms=False)

Find all members within the neighborhood of a single block.

Parameters:

center_blockint

The index of the block at the center of the neighborhood.

get_locationsbool, optional

If True, return the coordinates of the hood members.

get_termsbool, optional

If True, return the calculated “phi” terms of hood members. Note that a polynomial order must have been set, and terms calculated. See PolynomialTree.set_order(), and PolynomialTree.precalculate_phi_terms() for further information.

Returns:

members, [coordinates, terms]

members is a numpy.ndarray of int and shape (found_members,). If get_locations was set to True, coordinates is of shape (n_features, found_members). If get_terms was set to True, terms is of shape (n_terms, found_members).

property order

Return the order of the polynomial for the tree.

Returns:

int or numpy.ndarray (int)

A scalar value if orders for each feature are identical, or an array of values of shape (n_features,) if values are not identical.

property order_symmetry

Return whether the orders are symmetrical.

Orders are considered symmetrical when the orders of each feature are identical.

Returns:

bool

property order_varies

Return whether the order may be decreased.

The order of the polynomial may be reduced if specifically set by the user (fix_order=False) and the order is symmetrical. In this case, a subset of polynomial terms can be extracted from the original terms to describe a lower order polynomial.

Returns:

bool

property phi_terms_precalculated

Return whether the polynomial terms have been calculated.

Returns:

bool

precalculate_phi_terms()

Calculates polynomial terms for the tree coordinates and order.

Calculates the \(\Phi\) terms for the equation:

\[f(\Phi) = \hat{c} \cdot \Phi\]

The polynomial terms are dependent on the tree coordinates, and the order of polynomial fit. Please see polynomial_exponents() for a description on how terms are derived.

If the order is not fixed (i.e., is allowed to vary as marked by the order_varies attribute), a set of terms will be derived for all orders up to the order defined by the user. Please note that orders may only vary if the order is “symmetrical” as defined in PolynomialTree.set_order. In addition, a mapping relating terms to derivatives of the fit is also created in the derivative_term_map attribute, details of which can be found in polynomial_derivative_map(). When the order does vary, the terms for order k are given as:

tree.phi_terms[tree.order_term_indices[k]:

tree.order_term_indices[k+1]]

Returns:

None

set_order(order, fix_order=True)

Set the order(s) of polynomial fit for the resampling algorithm tree.

In addition to declaring the desired order of polynomial fit, the user may also opt to select an algorithm to validate the desired order of fit is possible given a distribution of samples. Please see resample_utils.check_orders() for a full description of available algorithms.

Throughout the resampling algorithm, orders are classified as either “symmetrical” or “asymmetrical”. An order is termed as symmetrical if it is the same for all features of the polynomial fit. i.e., the maximum exponent for each feature in a polynomial equation will be equal to the order. For example, a 2-dimensional 2nd order polynomial is of the form:

\[f(x, y) = c_0 + c_1 x + c_2 x^2 + c_3 y + c_4 x y + c_5 y^2\]

where the maximum exponent for \(x\) and \(y\) in any term is 2.

An order is considered “asymmetrical” if orders are not equal across features or dimensions. For example, a 2-dimensional polynomial with an order of 1 in \(x\), and 2 in \(y\) would have the form:

\[f(x, y) = c_0 + c_1 x + c_2 y + c_3 x y + c_4 y^2\]

where the maximum exponent of \(x\) is 1, and the maximum exponent of \(y\) is 2.

If orders are symmetrical, the user can allow the order to vary such that it passes the order validation algorithm. For instance, if only 2 samples exist for a 1-dimensional polynomial fit, and the user requested a 2nd order polynomial fit, the resampling algorithm will lower the order to 1, so that a fit can be performed (if the algorithm worked by counting the number of available samples). If orders are asymmetrical, this option is not available and fits will be aborted if they fail the order validation algorithm.

Parameters:

orderint or array_like (n_features,)

The symmetrical or asymmetrical orders respectively.

fix_orderbool, optional

If order is symmetrical, allow for a varying order in an attempt to pass the order validation algorithm (the order can only decrease).

Returns:

None