API#

Entry Points#

Canvas

`Canvas`([plot_width, plot_height, x_range, ...])	An abstract canvas representing the space in which to bin.
`Canvas.line`(source[, x, y, agg, axis, ...])	Compute a reduction by pixel, mapping data to pixels as one or more lines.
`Canvas.points`(source[, x, y, agg, geometry])	Compute a reduction by pixel, mapping data to pixels as points.
`Canvas.raster`(source[, layer, ...])	Sample a raster dataset by canvas size and bounds.
`Canvas.trimesh`(vertices, simplices[, mesh, ...])	Compute a reduction by pixel, mapping data to pixels as a triangle.
`Canvas.validate`()	Check that parameter settings are valid for this object
`Canvas.area`(source, x, y[, agg, axis, y_stack])	Compute a reduction by pixel, mapping data to pixels as a filled area region
`Canvas.polygons`(source, geometry[, agg])	Compute a reduction by pixel, mapping data to pixels as one or more filled polygons.
`Canvas.quadmesh`(source[, x, y, agg])	Samples a recti- or curvi-linear quadmesh by canvas size and bounds.

Pipeline

Pipeline(df, glyph[, agg, transform_fn, ...])

A datashading pipeline callback.

Edge Bundling#

`directly_connect_edges`	alias of `connect_edges`
`hammer_bundle`(*, accuracy, ...)	Iteratively group edges and return as paths suitable for datashading.

Glyphs#

`Point`(x, y)	A point, with center at `x` and `y`.
`Triangles`(x, y[, z, weight_type, interp])	An unstructured mesh of triangles, with vertices defined by `xs` and `ys`.
`PolygonGeom`(geometry)
`QuadMeshRaster`(x, y, name)
`QuadMeshRectilinear`(x, y, name)
`QuadMeshCurvilinear`(x, y, name)
`LineAxis0`(x, y)	A line, with vertices defined by `x` and `y`.
`LineAxis0Multi`(x, y)
`LinesAxis1`(x, y)	A collection of lines (on line per row) with vertices defined by the lists of columns in `x` and `y`
`LinesAxis1XConstant`(x, y)
`LinesAxis1YConstant`(x, y)
`LinesAxis1Ragged`(x, y)
`LineAxis1Geometry`(geometry)
`AreaToZeroAxis0`(x, y)	A filled area glyph.
`AreaToZeroAxis0Multi`(x, y)
`AreaToZeroAxis1`(x, y)
`AreaToZeroAxis1XConstant`(x, y)
`AreaToZeroAxis1YConstant`(x, y)
`AreaToZeroAxis1Ragged`(x, y)
`AreaToLineAxis0`(x, y, y_stack)	A filled area glyph The area to be filled is the region from the line defined by `x` and `y[0]` and the line defined by `x` and `y[1]`.
`AreaToLineAxis0Multi`(x, y, y_stack)
`AreaToLineAxis1`(x, y, y_stack)
`AreaToLineAxis1XConstant`(x, y, y_stack)
`AreaToLineAxis1YConstant`(x, y, y_stack)
`AreaToLineAxis1Ragged`(x, y, y_stack)

Reductions#

`any`([column])	Whether any elements in `column` map to each bin.
`count`([column, self_intersect])	Count elements in each bin, returning the result as a uint32, or a float32 if using antialiasing.
`by`(cat_column[, reduction])	Apply the provided reduction separately per category.
`first`([column])	First value encountered in `column`.
`last`([column])	Last value encountered in `column`.
`m2`([column])	Sum of square differences from the mean of all elements in `column`.
`max`([column])	Maximum value of all elements in `column`.
`mean`([column])	Mean of all elements in `column`.
`min`([column])	Minimum value of all elements in `column`.
`mode`([column])	Mode (most common value) of all the values encountered in `column`.
`std`([column])	Standard Deviation of all elements in `column`.
`sum`([column, self_intersect])	Sum of all elements in `column`.
`summary`(**kwargs)	A collection of named reductions.
`var`([column])	Variance of all elements in `column`.
`where`(selector[, lookup_column])	Returns values from a `lookup_column` corresponding to a `selector` reduction that is applied to some other column.

The table below indicates which Reduction classes are supported on the CPU (e.g. using pandas), on CPU with Dask (e.g. using dask.dataframe), on the GPU (e.g. using cudf), and on the GPU with Dask (e.g. using dask-cudf). The final two columns indicate which reductions support antialiased lines and which can be used as the selector in a where reduction.

	CPU	CPU + Dask	GPU	GPU + Dask	Antialiasing	Within `where`
`any`	yes	yes	yes	yes	yes
`by`	yes	yes	yes	yes	yes
`count`	yes	yes	yes	yes	yes
`first`	yes	yes	yes	yes	yes	yes
`first_n`	yes	yes	yes	yes	yes	yes
`last`	yes	yes	yes	yes	yes	yes
`last_n`	yes	yes	yes	yes	yes	yes
`max`	yes	yes	yes	yes	yes	yes
`max_n`	yes	yes	yes	yes	yes	yes
`mean`	yes	yes	yes	yes	yes
`min`	yes	yes	yes	yes	yes	yes
`min_n`	yes	yes	yes	yes	yes	yes
`std`	yes	yes	yes	yes
`sum`	yes	yes	yes	yes	yes
`var`	yes	yes	yes	yes

The mode reduction is not listed in the table and can only be used with Canvas.raster. A by reduction supports anything that its contained reduction (that is applied separately to each category) supports.

Categorizers

`category_binning`(column, lower, upper, nbins)	A variation on category_codes that assigns categories by binning a continuous-valued column.
`category_modulo`(column, modulo[, offset])	A variation on category_codes that assigns categories using an integer column, modulo a base.

Transfer Functions#

Image

`Image`(data, coords, dims, name, attrs, ...)
`Image.to_bytesio`([format, origin])
`Image.to_pil`([origin])

Images

`Images`(*images)	A list of HTML-representable objects to display in a table.
`Images.cols`(n)	Set the number of columns to use in the HTML table.

Other

`dynspread`(img[, threshold, max_px, shape, ...])	Spread pixels in an image dynamically based on the image density.
`set_background`(img[, color, name])	Return a new image, with the background set to color.
`shade`(agg[, cmap, color_key, how, alpha, ...])	Convert a DataArray to an image by choosing an RGBA pixel color for each value.
`spread`(img[, px, shape, how, mask, name])	Spread pixels in an image.
`stack`(imgs, *kwargs)	Combine images together, overlaying later images onto earlier ones.

Definitions#

class datashader.Canvas(plot_width=600, plot_height=600, x_range=None, y_range=None, x_axis_type='linear', y_axis_type='linear')[source]#

An abstract canvas representing the space in which to bin.

Parameters:

plot_width, plot_heightint, optional: Width and height of the output aggregate in pixels.
x_range, y_rangetuple, optional: A tuple representing the bounds inclusive space [min, max] along the axis.
x_axis_type, y_axis_typestr, optional: The type of the axis. Valid options are 'linear' [default], and 'log'.

Methods

`area`(source, x, y[, agg, axis, y_stack])	Compute a reduction by pixel, mapping data to pixels as a filled area region
`line`(source[, x, y, agg, axis, geometry, ...])	Compute a reduction by pixel, mapping data to pixels as one or more lines.
`points`(source[, x, y, agg, geometry])	Compute a reduction by pixel, mapping data to pixels as points.
`polygons`(source, geometry[, agg])	Compute a reduction by pixel, mapping data to pixels as one or more filled polygons.
`quadmesh`(source[, x, y, agg])	Samples a recti- or curvi-linear quadmesh by canvas size and bounds.
`raster`(source[, layer, upsample_method, ...])	Sample a raster dataset by canvas size and bounds.
`trimesh`(vertices, simplices[, mesh, agg, ...])	Compute a reduction by pixel, mapping data to pixels as a triangle.
`validate`()	Check that parameter settings are valid for this object

validate_ranges
validate_size

class datashader.Pipeline(df, glyph, agg=count(), transform_fn=<function identity>, color_fn=<function shade>, spread_fn=<function dynspread>, width_scale=1.0, height_scale=1.0)[source]#

A datashading pipeline callback.

Given a declarative specification, creates a callable with the following signature:

callback(x_range, y_range, width, height)

where x_range and y_range form the bounding box on the viewport, and width and height specify the output image dimensions.

Parameters:

dfpandas.DataFrame, dask.DataFrame
glyphGlyph: The glyph to bin by.
aggReduction, optional: The reduction to compute per-pixel. Default is count().
transform_fncallable, optional: A callable that takes the computed aggregate as an argument, and returns another aggregate. This can be used to do preprocessing before passing to the color_fn function.
color_fncallable, optional: A callable that takes the output of tranform_fn, and returns an Image object. Default is shade.
spread_fncallable, optional: A callable that takes the output of color_fn, and returns another Image object. Default is dynspread.
height_scale: float, optional: Factor by which to scale the provided height
width_scale: float, optional: Factor by which to scale the provided width

Methods

__call__([x_range, y_range, width, height])

Compute an image from the specified pipeline.

datashader.bundling.directly_connect_edges[source]#: alias of connect_edges

class datashader.bundling.hammer_bundle(*, accuracy, advect_iterations, batch_size, decay, initial_bandwidth, iterations, max_segment_length, min_segment_length, tension, use_dask, include_edge_id, source, target, weight, x, y, name)[source]#

Iteratively group edges and return as paths suitable for datashading.

Breaks each edge into a path with multiple line segments, and iteratively curves this path to bundle edges into groups.

Methods

__call__(nodes, edges, **params)

Convert a graph data structure into a path structure for plotting

Parameter Definitions

Parameters inherited from:

datashader.bundling.connect_edges: x, y, source, target, include_edge_id

weight = String(allow_None=True, default='weight', label='Weight'): Column name for each edge weight. If None, weights are ignored.
initial_bandwidth = Number(bounds=(0.0, None), default=0.05, inclusive_bounds=(True, True), label='Initial bandwidth'): Initial value of the bandwidth….
decay = Number(bounds=(0.0, 1.0), default=0.7, inclusive_bounds=(True, True), label='Decay'): Rate of decay in the bandwidth value, with 1.0 indicating no decay.
iterations = Integer(bounds=(1, None), default=4, inclusive_bounds=(True, True), label='Iterations'): Number of passes for the smoothing algorithm
batch_size = Integer(bounds=(1, None), default=20000, inclusive_bounds=(True, True), label='Batch size'): Number of edges to process together
tension = Number(bounds=(0, None), default=0.3, inclusive_bounds=(True, True), label='Tension'): Exponential smoothing factor to use when smoothing
accuracy = Integer(bounds=(1, 65535), default=500, inclusive_bounds=(True, True), label='Accuracy'): Number of entries in table for…
advect_iterations = Integer(bounds=(0, None), default=50, inclusive_bounds=(True, True), label='Advect iterations'): Number of iterations to move edges along gradients
min_segment_length = Number(bounds=(0, None), default=0.008, inclusive_bounds=(True, True), label='Min segment length'): Minimum length (in data space?) for an edge segment
max_segment_length = Number(bounds=(0, None), default=0.016, inclusive_bounds=(True, True), label='Max segment length'): Maximum length (in data space?) for an edge segment
use_dask = Boolean(default=False, label='Use dask'): Whether to use dask to parallelize the computation.

class datashader.glyphs.Point(x, y)[source]#

A point, with center at x and y.

Points map each record to a single bin. Points falling exactly on the upper bounds are treated as a special case, mapping into the previous bin rather than being cropped off.

Parameters:

x, ystr: Column names for the x and y coordinates of each point.

class datashader.glyphs.Triangles(x, y, z=None, weight_type=True, interp=True)[source]#

An unstructured mesh of triangles, with vertices defined by xs and ys.

Parameters:

xs, ys, zslist of str: Column names of x, y, and (optional) z coordinates of each vertex.

class datashader.glyphs.PolygonGeom(geometry)[source]#

Attributes:

geom_dtypes

class datashader.glyphs.QuadMeshRaster(x, y, name)[source]#

Methods

is_upsample

class datashader.glyphs.QuadMeshRectilinear(x, y, name)[source]#

Methods

compute_bounds_dask
compute_x_bounds
compute_y_bounds
infer_interval_breaks

class datashader.glyphs.QuadMeshCurvilinear(x, y, name)[source]#

Methods

compute_bounds_dask
compute_x_bounds
compute_y_bounds
infer_interval_breaks

class datashader.glyphs.LineAxis0(x, y)[source]#

A line, with vertices defined by x and y.

Parameters:

x, ystr: Column names for the x and y coordinates of each vertex.

class datashader.glyphs.LineAxis0Multi(x, y)[source]#

Attributes:

x_label
y_label

Methods

compute_bounds_dask
compute_x_bounds
compute_y_bounds
required_columns
validate

class datashader.glyphs.LinesAxis1(x, y)[source]#

A collection of lines (on line per row) with vertices defined by the lists of columns in x and y

Parameters:

x, ylist: Lists of column names for the x and y coordinates

Attributes:

x_label
y_label

Methods

compute_bounds_dask
compute_x_bounds
compute_y_bounds
required_columns
validate

class datashader.glyphs.LinesAxis1XConstant(x, y)[source]#

Methods

compute_bounds_dask
compute_x_bounds
required_columns
validate

class datashader.glyphs.LinesAxis1YConstant(x, y)[source]#

Methods

compute_bounds_dask
compute_y_bounds
required_columns
validate

class datashader.glyphs.LinesAxis1Ragged(x, y)[source]#

Methods

compute_bounds_dask
compute_x_bounds
compute_y_bounds
required_columns
validate

class datashader.glyphs.LineAxis1Geometry(geometry)[source]#

Attributes:

geom_dtypes

class datashader.glyphs.AreaToZeroAxis0(x, y)[source]#

A filled area glyph. The area to be filled is the region from the line defined by x and y and the y=0 line

Parameters:

x, y: Column names for the x and y coordinates of each vertex.

Methods

compute_bounds_dask
compute_y_bounds

class datashader.glyphs.AreaToZeroAxis0Multi(x, y)[source]#

Attributes:

x_label
y_label

Methods

compute_bounds_dask
compute_x_bounds
compute_y_bounds
required_columns
validate

class datashader.glyphs.AreaToZeroAxis1(x, y)[source]#

Attributes:

x_label
y_label

Methods

compute_bounds_dask
compute_x_bounds
compute_y_bounds
required_columns
validate

class datashader.glyphs.AreaToZeroAxis1XConstant(x, y)[source]#

Methods

compute_bounds_dask
compute_x_bounds
required_columns
validate

class datashader.glyphs.AreaToZeroAxis1YConstant(x, y)[source]#

Methods

compute_bounds_dask
compute_y_bounds
required_columns
validate

class datashader.glyphs.AreaToZeroAxis1Ragged(x, y)[source]#

Methods

compute_bounds_dask
compute_x_bounds
compute_y_bounds
required_columns
validate

class datashader.glyphs.AreaToLineAxis0(x, y, y_stack)[source]#

A filled area glyph The area to be filled is the region from the line defined by x and y[0] and the line defined by x and y[1].

Parameters:

x: Column names for the x and y coordinates of each vertex.
y: List or tuple of length two containing the column names of the y-coordinates of the two curves that define the area region.

Methods

compute_bounds_dask
compute_y_bounds

class datashader.glyphs.AreaToLineAxis0Multi(x, y, y_stack)[source]#

Attributes:

x_label
y_label

Methods

compute_bounds_dask
compute_x_bounds
compute_y_bounds
required_columns
validate

class datashader.glyphs.AreaToLineAxis1(x, y, y_stack)[source]#

Attributes:

x_label
y_label

Methods

compute_bounds_dask
compute_x_bounds
compute_y_bounds
required_columns
validate

class datashader.glyphs.AreaToLineAxis1XConstant(x, y, y_stack)[source]#

Methods

compute_bounds_dask
compute_x_bounds
required_columns
validate

class datashader.glyphs.AreaToLineAxis1YConstant(x, y, y_stack)[source]#

Methods

compute_bounds_dask
compute_y_bounds
required_columns
validate

class datashader.glyphs.AreaToLineAxis1Ragged(x, y, y_stack)[source]#

Methods

compute_bounds_dask
compute_x_bounds
compute_y_bounds
required_columns
validate

class datashader.reductions.any(column=None)[source]#

Whether any elements in column map to each bin.

Parameters:

columnstr, optional: If provided, any elements in column that are NaN are skipped.

Methods

out_dshape

class datashader.reductions.by(cat_column, reduction=count())[source]#

Apply the provided reduction separately per category.

Parameters:

cats: str or CategoryPreprocess instance: Name of column to aggregate over, or a categorizer object that returns categories. Resulting aggregate has an outer dimension axis along the categories present.
reductionReduction: Per-category reduction function.

Attributes:

cat_column
inputs
nan_check_column
val_column

Methods

`is_categorical`()	Return `True` if this is or contains a categorical reduction.
`is_where`()	Return `True` if this is a `where` reduction or directly wraps a where reduction.
`uses_cuda_mutex`()	Return `True` if this Reduction needs to use a CUDA mutex to ensure that it is threadsafe across CUDA threads.
`uses_row_index`(cuda, partitioned)	Return `True` if this Reduction uses a row index virtual column.

out_dshape
validate

class datashader.reductions.count(column=None, self_intersect=True)[source]#

Count elements in each bin, returning the result as a uint32, or a float32 if using antialiasing.

Parameters:

columnstr, optional: If provided, only counts elements in column that are not NaN. Otherwise, counts every element.

Methods

out_dshape

class datashader.reductions.count_cat(column)[source]#

Count of all elements in column, grouped by category. Alias for by(…,count()), for backwards compatibility.

Parameters:

columnstr: Name of the column to aggregate over. Column data type must be categorical. Resulting aggregate has a outer dimension axis along the categories present.

class datashader.reductions.first(column: str | SpecialColumn | None = None)[source]#

First value encountered in column.

Useful for categorical data where an actual value must always be returned, not an average or other numerical calculation.

Currently only supported for rasters, externally to this class.

Parameters:

columnstr: Name of the column to aggregate over. If the data type is floating point, NaN values in the column are skipped.

class datashader.reductions.first_n(column=None, n=1)[source]#

class datashader.reductions.last(column: str | SpecialColumn | None = None)[source]#

Last value encountered in column.

Useful for categorical data where an actual value must always be returned, not an average or other numerical calculation.

Currently only supported for rasters, externally to this class.

Parameters:

columnstr: Name of the column to aggregate over. If the data type is floating point, NaN values in the column are skipped.

class datashader.reductions.last_n(column=None, n=1)[source]#

class datashader.reductions.m2(column: str | SpecialColumn | None = None)[source]#

Sum of square differences from the mean of all elements in column.

Intermediate value for computing var and std, not intended to be used on its own.

Parameters:

columnstr: Name of the column to aggregate over. Column data type must be numeric. NaN values in the column are skipped.

Methods

uses_cuda_mutex()

Return True if this Reduction needs to use a CUDA mutex to ensure that it is threadsafe across CUDA threads.

class datashader.reductions.max(column: str | SpecialColumn | None = None)[source]#

Maximum value of all elements in column.

Parameters:

columnstr: Name of the column to aggregate over. Column data type must be numeric. NaN values in the column are skipped.

class datashader.reductions.max_n(column=None, n=1)[source]#

Methods

uses_cuda_mutex()

Return True if this Reduction needs to use a CUDA mutex to ensure that it is threadsafe across CUDA threads.

class datashader.reductions.mean(column: str | SpecialColumn | None = None)[source]#

Mean of all elements in column.

Parameters:

columnstr: Name of the column to aggregate over. Column data type must be numeric. NaN values in the column are skipped.

class datashader.reductions.min(column: str | SpecialColumn | None = None)[source]#

Minimum value of all elements in column.

Parameters:

columnstr: Name of the column to aggregate over. Column data type must be numeric. NaN values in the column are skipped.

class datashader.reductions.min_n(column=None, n=1)[source]#

Methods

uses_cuda_mutex()

Return True if this Reduction needs to use a CUDA mutex to ensure that it is threadsafe across CUDA threads.

class datashader.reductions.mode(column: str | SpecialColumn | None = None)[source]#

Mode (most common value) of all the values encountered in column.

Useful for categorical data where an actual value must always be returned, not an average or other numerical calculation.

Currently only supported for rasters, externally to this class. Implementing it for other glyph types would be difficult due to potentially unbounded data storage requirements to store indefinite point or line data per pixel.

Parameters:

columnstr: Name of the column to aggregate over. If the data type is floating point, NaN values in the column are skipped.

Methods

out_dshape

class datashader.reductions.std(column: str | SpecialColumn | None = None)[source]#

Standard Deviation of all elements in column.

Parameters:

columnstr: Name of the column to aggregate over. Column data type must be numeric. NaN values in the column are skipped.

class datashader.reductions.sum(column=None, self_intersect=True)[source]#

Sum of all elements in column.

Elements of resulting aggregate are nan if they are not updated.

Parameters:

columnstr: Name of the column to aggregate over. Column data type must be numeric. NaN values in the column are skipped.

class datashader.reductions.summary(**kwargs)[source]#

A collection of named reductions.

Computes all aggregates simultaneously, output is stored as a xarray.Dataset.

Attributes:

inputs

Methods

is_categorical
uses_row_index
validate

Notes

A single pass of the source dataset using antialiased lines can either be performed using a single-stage aggregation (e.g. self_intersect=True) or two stages (self_intersect=False). If a summary contains a count or sum reduction with self_intersect=False, or any of first, last or min, then the antialiased line pass will be performed in two stages.

Examples

A reduction for computing the mean of column “a”, and the sum of column “b” for each bin, all in a single pass.

>>> import datashader as ds
>>> red = ds.summary(mean_a=ds.mean('a'), sum_b=ds.sum('b'))

class datashader.reductions.var(column: str | SpecialColumn | None = None)[source]#

Variance of all elements in column.

Parameters:

columnstr: Name of the column to aggregate over. Column data type must be numeric. NaN values in the column are skipped.

class datashader.reductions.where(selector: Reduction, lookup_column: str | None = None)[source]#

Returns values from a lookup_column corresponding to a selector reduction that is applied to some other column.

If lookup_column is None then it uses the index of the row in the DataFrame instead of a named column. This is returned as an int64 aggregation with -1 used to denote no value.

Parameters:

selector: Reduction: Reduction used to select the values of the lookup_column which are returned by this where reduction.
lookup_columnstr | None: Column containing values that are returned from this where reduction, or None to return row indexes instead.

Methods

`is_where`()	Return `True` if this is a `where` reduction or directly wraps a where reduction.
`uses_cuda_mutex`()	Return `True` if this Reduction needs to use a CUDA mutex to ensure that it is threadsafe across CUDA threads.
`uses_row_index`(cuda, partitioned)	Return `True` if this Reduction uses a row index virtual column.

out_dshape
validate

Examples

>>> canvas.line(df, 'x', 'y', agg=ds.where(ds.max("value"), "other"))

This returns the values of the “other” column that correspond to the maximum of the “value” column in each bin.

class datashader.transfer_functions.Image(data: ~typing.Any = <NA>, coords: ~collections.abc.Sequence[~collections.abc.Sequence | ~pandas.core.indexes.base.Index | ~xarray.core.dataarray.DataArray | ~xarray.core.variable.Variable | ~numpy.ndarray] | ~collections.abc.Mapping | None = None, dims: str | ~collections.abc.Iterable[~collections.abc.Hashable] | None = None, name: ~collections.abc.Hashable | None = None, attrs: ~collections.abc.Mapping | None = None, indexes: ~collections.abc.Mapping[~collections.abc.Hashable, ~xarray.core.indexes.Index] | None = None, fastpath: bool = False)[source]#

Methods

`item`(*args)	Copy an element of an array to a standard Python scalar and return it.
`searchsorted`(v[, side, sorter])	Find indices where elements of v should be inserted in a to maintain order.

to_bytesio
to_pil

item(*args)[source]#

Copy an element of an array to a standard Python scalar and return it.

Parameters:

*argsArguments (variable number and type)

none: in this case, the method only works for arrays with one element (a.size == 1), which element is copied into a standard Python scalar object and returned.
int_type: this argument is interpreted as a flat index into the array, specifying which element to copy and return.
tuple of int_types: functions as does a single int_type argument, except that the argument is interpreted as an nd-index into the array.

Returns:

zStandard Python scalar object: A copy of the specified element of the array as a suitable Python scalar

Notes

When the data type of a is longdouble or clongdouble, item() returns a scalar array object because there is no available Python scalar that would not lose information. Void arrays return a buffer object for item(), unless fields are defined, in which case a tuple is returned.

item is very similar to a[args], except, instead of an array scalar, a standard Python scalar is returned. This can be useful for speeding up access to elements of the array and doing arithmetic on elements of the array using Python’s optimized math.

Examples

>>> import numpy as np
>>> np.random.seed(123)
>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[2, 2, 6],
       [1, 3, 6],
       [1, 0, 1]])
>>> x.item(3)
1
>>> x.item(7)
0
>>> x.item((0, 1))
2
>>> x.item((2, 2))
1

For an array with object dtype, elements are returned as-is.

>>> a = np.array([np.int64(1)], dtype=object)
>>> a.item() #return np.int64
np.int64(1)

searchsorted(v, side='left', sorter=None)[source]#

Find indices where elements of v should be inserted in a to maintain order.

For full documentation, see numpy.searchsorted

See also

numpy.searchsorted: equivalent function

datashader.transfer_functions.dynspread(img, threshold=0.5, max_px=3, shape='circle', how=None, name=None)[source]#

Spread pixels in an image dynamically based on the image density.

Spreading expands each pixel a certain number of pixels on all sides according to a given shape, merging pixels using a specified compositing operator. This can be useful to make sparse plots more visible. Dynamic spreading determines how many pixels to spread based on a density heuristic. Spreading starts at 1 pixel, and stops when the fraction of adjacent non-empty pixels reaches the specified threshold, or the max_px is reached, whichever comes first.

Parameters:

imgImage
thresholdfloat, optional: A tuning parameter in [0, 1], with higher values giving more spreading.
max_pxint, optional: Maximum number of pixels to spread on all sides.
shapestr, optional: The shape to spread by. Options are ‘circle’ [default] or ‘square’.
howstr, optional: The name of the compositing operator to use when combining pixels. Default of None uses ‘over’ operator for Image objects and ‘add’ operator otherwise.

datashader.transfer_functions.set_background(img, color=None, name=None)[source]#

Return a new image, with the background set to color.

Parameters:

imgImage
colorcolor name or tuple, optional: The background color. Can be specified either by name, hexcode, or as a tuple of (red, green, blue) values.

datashader.transfer_functions.shade(agg, cmap=['lightblue', 'darkblue'], color_key=['#e41a1c', '#377eb8', '#4daf4a', '#984ea3', '#ff7f00', '#ffff33', '#a65628', '#f781bf', '#999999', '#66c2a5', '#fc8d62', '#8da0cb', '#a6d854', '#ffd92f', '#e5c494', '#ffffb3', '#fb8072', '#fdb462', '#fccde5', '#d9d9d9', '#ccebc5', '#ffed6f'], how='eq_hist', alpha=255, min_alpha=40, span=None, name=None, color_baseline=None, rescale_discrete_levels=False)[source]#

Convert a DataArray to an image by choosing an RGBA pixel color for each value.

Requires a DataArray with a single data dimension, here called the “value”, indexed using either 2D or 3D coordinates.

For a DataArray with 2D coordinates, the RGB channels are computed from the values by interpolated lookup into the given colormap cmap. The A channel is then set to the given fixed alpha value for all non-zero values, and to zero for all zero values. A dictionary color_key that specifies categories (values in agg) and corresponding colors can be provided to support discrete coloring 2D aggregates, i.e aggregates with a single category per pixel, with no mixing. The A channel is set the given alpha value for all pixels in the categories specified in color_key, and to zero otherwise.

DataArrays with 3D coordinates are expected to contain values distributed over different categories that are indexed by the additional coordinate. Such an array would reduce to the 2D-coordinate case if collapsed across the categories (e.g. if one did aggc.sum(dim='cat') for a categorical dimension cat). The RGB channels for the uncollapsed, 3D case are mixed from separate values over all categories. They are computed by averaging the colors in the provided color_key (with one color per category), weighted by the array’s value for that category. The A channel is then computed from the array’s total value collapsed across all categories at that location, ranging from the specified min_alpha to the maximum alpha value (255).

Parameters:

aggDataArray
cmaplist of colors or matplotlib.colors.Colormap, optional: The colormap to use for 2D agg arrays. Can be either a list of colors (specified either by name, RGBA hexcode, or as a tuple of (red, green, blue) values.), or a matplotlib colormap object. Default is ["lightblue", "darkblue"].
color_keydict or iterable: The colors to use for a categorical agg array. In 3D case, it can be either a dict mapping from field name to colors, or an iterable of colors in the same order as the record fields, and including at least that many distinct colors. In 2D case, color_key must be a dict where all keys are categories, and values are corresponding colors. Number of categories does not necessarily equal to the number of unique values in the agg DataArray.
howstr or callable, optional: The interpolation method to use, for the cmap of a 2D DataArray or the alpha channel of a 3D DataArray. Valid strings are ‘eq_hist’ [default], ‘cbrt’ (cube root), ‘log’ (logarithmic), and ‘linear’. Callables take 2 arguments - a 2-dimensional array of magnitudes at each pixel, and a boolean mask array indicating missingness. They should return a numeric array of the same shape, with NaN values where the mask was True.
alphaint, optional: Value between 0 - 255 representing the alpha value to use for colormapped pixels that contain data (i.e. non-NaN values). Also used as the maximum alpha value when alpha is indicating data value, such as for single colors or categorical plots. Regardless of this value, NaN values are set to be fully transparent when doing colormapping.
min_alphafloat, optional: The minimum alpha value to use for non-empty pixels when alpha is indicating data value, in [0, 255]. Use a higher value to avoid undersaturation, i.e. poorly visible low-value datapoints, at the expense of the overall dynamic range. Note that min_alpha will not take any effect when doing discrete categorical coloring for 2D case as the aggregate can have only a single value to denote the category.
spanlist of min-max range, optional: Min and max data values to use for 2D colormapping, and 3D alpha interpolation, when wishing to override autoranging.
namestring name, optional: Optional string name to give to the Image object to return, to label results for display.
color_baselinefloat or None: Baseline for calculating how categorical data mixes to determine the color of a pixel. The color for each category is weighted by how far that category’s value is above this baseline value, out of the total sum across all categories’ values. A value of zero is appropriate for counts and for other physical quantities for which zero is a meaningful reference; each category then contributes to the final color in proportion to how much each category contributes to the final sum. However, if values can be negative or if they are on an interval scale where values e.g. twice as far from zero are not twice as high (such as temperature in Fahrenheit), then you will need to provide a suitable baseline value for use in calculating color mixing. A value of None (the default) means to take the minimum across the entire aggregate array, which is safe but may not weight the colors as you expect; any categories with values near this baseline will contribute almost nothing to the final color. As a special case, if the only data present in a pixel is at the baseline level, the color will be an evenly weighted average of all such categories with data (to avoid the color being undefined in this case).
rescale_discrete_levelsboolean, optional: If how='eq_hist and there are only a few discrete values, then rescale_discrete_levels=True decreases the lower limit of the autoranged span so that the values are rendering towards the (more visible) top of the cmap range, thus avoiding washout of the lower values. Has no effect if how!=`eq_hist. Default is False.

datashader.transfer_functions.spread(img, px=1, shape='circle', how=None, mask=None, name=None)[source]#

Spread pixels in an image.

Spreading expands each pixel a certain number of pixels on all sides according to a given shape, merging pixels using a specified compositing operator. This can be useful to make sparse plots more visible.

Parameters:

imgImage or other DataArray
pxint, optional: Number of pixels to spread on all sides
shapestr, optional: The shape to spread by. Options are ‘circle’ [default] or ‘square’.
howstr, optional: The name of the compositing operator to use when combining pixels. Default of None uses ‘over’ operator for Image objects and ‘add’ operator otherwise.
maskndarray, shape (M, M), optional: The mask to spread over. If provided, this mask is used instead of generating one based on px and shape. Must be a square array with odd dimensions. Pixels are spread from the center of the mask to locations where the mask is True.
namestring name, optional: Optional string name to give to the Image object to return, to label results for display.

datashader.transfer_functions.stack(*imgs, **kwargs)[source]#

Combine images together, overlaying later images onto earlier ones.

Parameters:

imgsiterable of Image: The images to combine.
howstr, optional: The compositing operator to combine pixels. Default is ‘over’.