weave.dimension

Smoothing dimension specifications.

class weave.dimension.Dimension(name, coordinates=None, kernel='identity', distance=None, radius=None, exponent=None, version=None, distance_dict=None)

Smoothing dimension specifications.

Dimension class to specify smoothing dimension column names, kernel function, distance function, and relevant parameters.

name

Dimension name.

Column in data frame containing the ID of points in the given dimension. For example, ‘age_id’, ‘year_id’, or ‘location_id’.

Type:

str

coordinates

Dimension coordinates.

Column(s) in data frame containing the coordinates of points in the given dimension. For example, ‘age_mid’, [‘lat’, ‘lon’], or [‘super_region’, ‘region’, ‘country’]. Can be same as name attribute if dimension is 1D.

Type:

list of str

kernel

Kernel function name.

Name of kernel function to compute smoothing weights.

See also

weave.kernels

Type:

{‘exponential’, ‘tricubic’, ‘depth’, ‘inverse’, ‘identity’}

distance

Distance function name.

Name of distance function to compute distance between points.

See also

weave.distance

Type:

{‘euclidean’, ‘tree’, ‘dictionary’}

radius

Kernel radius.

Kernel radius if kernel is ‘exponential’, ‘depth’, or ‘inverse’.

Type:

positive number, optional

exponent

Kernel exponent.

Kernel exponent if kernel is ‘tricubic’.

Type:

positive number, optional

version

Kernel version.

Kernel version if kernel is ‘depth’.

Type:

{‘codem’, ‘stgpr’}, optional

distance_dict

Dictionary of distances between points.

User-defined dictionary of distances between points if distance attribute is ‘dictionary’. Dictionary keys are tuples of point ID pairs, and dictionary values are the corresponding distances.

Type:

dict of {(number, number): number}, optional

Create smoothing dimension.

Parameters:

• name (str) – Dimension name.

• coordinates (str or list of str, optional) – Dimension coordinates, if different from name.

• kernel ({'exponential', 'tricubic', 'depth', 'inverse', 'identity'}, optional) – Kernel function name. Default is ‘identity’.

• distance ({'euclidean', 'tree', 'dictionary'}, optional) – Distance function name. If None, default distance function is assigned based on kernel.

• radius (positive number, optional) – Kernel radius if kernel is ‘exponential’, ‘depth’, or ‘inverse’. For depth kernel, radius must be a float in (0.5, 1).

• exponent (positive number, optional) – Kernel exponent if kernel is ‘tricubic’.

• version ({'codem', 'stgpr'}, optional) – Kernel version if kernel is ‘depth’. Default is ‘codem’.

• distance_dict (dict of {(number, number): number}, optional) – Dictionary of distances between points if distance is ‘dictionary’. Dictionary values must be nonnegative.

Notes

Kernel-specific parameters and default attributes are given in the table below.

Kernel	Parameters	Parameter types	Default distance
exponential	radius	Positive number	euclidean
tricubic	exponent	Positive number	euclidean
depth	radius	float in \((0.5, 1)\)	tree
	version	{‘codem’, ‘stgpr’}, optional (default is ‘codem’)
inverse	radius	Positive number	euclidean
identity			euclidean

The identity kernel does not have any kernel parameters because the weight values are equal to the distance values.

Examples

Dimensions with exponential kernel and default Euclidean distance.

>>> from weave.dimension import Dimension
>>> age = Dimension(
        name='age_id',
        coordinates='age_mean',
        kernel='exponential',
        radius=0.5
    )
>>> location = Dimension(
        name='location_id',
        coordinates=['lat', 'lon'],
        kernel='exponential',
        radius=0.5
    )

Dimension with tricubic kernel and default Euclidean distance.

>>> from weave.dimension import Dimension
>>> year = Dimension(
        name='year_id',
        kernel='tricubic',
        exponent=3
    )

Dimension with tricubic kernel and dictionary distance.

>>> from weave.dimension import Dimension
>>> location = Dimension(
        name='location_id',
        kernel='tricubic',
        exponent=3,
        distance='dictionary',
        distance_dict={
            (4, 4): 0,
            (4, 5): 1,
            (4, 6): 2,
            (5, 4): 1,
            (5, 5): 0,
            (5, 6): 2,
            (6, 4): 2,
            (6, 5): 2,
            (6, 6): 0
        }
    )

Dimension with depth kernel and default tree distance.

>>> from weave.dimension import Dimension
>>> location = Dimension(
        name='location_id',
        coordinates=['super_region', 'region', 'country'],
        kernel='depth',
        radius=0.9
    )

Dimension with identity kernel and default Euclidean distance.

>>> from weave.dimension import Dimension
>>> location = Dimension(
        name='location_id',
        coordinates=['lat', 'lon'],
        kernel='identity'
    )