spatialdata.rasterize#
- spatialdata.rasterize(data, axes, min_coordinate, max_coordinate, target_coordinate_system, target_unit_to_pixels=None, target_width=None, target_height=None, target_depth=None, sdata=None, value_key=None, table_name=None, return_regions_as_labels=False, agg_func=None, return_single_channel=None)#
Rasterize a
SpatialData
object or aSpatialElement
(image, labels, points, shapes).- Parameters:
data (
Union
[SpatialData
,DataArray
,DataTree
,GeoDataFrame
,DataFrame
,str
]) – TheSpatialData
object orSpatialElement
to rasterize. In alternative, the name of theSpatialElement
in theSpatialData
object, when theSpatialData
object is passed tovalues_sdata
.axes (
tuple
[str
,...
]) – The axes thatmin_coordinate
andmax_coordinate
refer to.min_coordinate (
list
[Union
[int
,float
]] |ndarray
[Any
,dtype
[float64
]]) – The minimum coordinates of the bounding box.max_coordinate (
list
[Union
[int
,float
]] |ndarray
[Any
,dtype
[float64
]]) – The maximum coordinates of the bounding box.target_coordinate_system (
str
) – The coordinate system in which we define the bounding box. This will also be the coordinate system of the produced rasterized image.target_unit_to_pixels (
Optional
[float
] (default:None
)) – The number of pixels per unit that the target image should have. It is mandatory to specify precisely one of the following options:target_unit_to_pixels
,target_width
,target_height
,target_depth
.target_width (
Optional
[float
] (default:None
)) – The width of the target image in units. It is mandatory to specify precisely one of the following options:target_unit_to_pixels
,target_width
,target_height
,target_depth
.target_height (
Optional
[float
] (default:None
)) – The height of the target image in units. It is mandatory to specify precisely one of the following options:target_unit_to_pixels
,target_width
,target_height
,target_depth
.target_depth (
Optional
[float
] (default:None
)) – The depth of the target image in units. It is mandatory to specify precisely one of the following options:target_unit_to_pixels
,target_width
,target_height
,target_depth
.sdata (
Optional
[SpatialData
] (default:None
)) –SpatialData
object containing the values to aggregate ifvalue_key
refers to values from a table. Must beNone
whendata
is aSpatialData
object.value_key (
Optional
[str
] (default:None
)) –Name of the column containing the values to aggregate; can refer both to numerical or categorical values.
The key can be:
the name of a column(s) in the dataframe (Dask
DataFrame
for points orGeoDataFrame
for shapes);the name of obs column(s) in the associated
AnnData
table (for points, shapes, and labels);the name of a var(s), referring to the column(s) of the X matrix in the table (for points, shapes, and labels).
See the notes for more details on the default behavior. Must be
None
whendata
is aSpatialData
object.table_name (
Optional
[str
] (default:None
)) – The table optionally containing thevalue_key
and the name of the table in the returnedSpatialData
object. Must beNone
whendata
is aSpatialData
object, otherwise it assumes the default value of'table'
.return_regions_as_labels (
bool
(default:False
)) – By default, single-scale images of shape(c, y, x)
are returned. IfTrue
, returns labels and shapes as labels of shape(y, x)
as opposed to an image of shape(c, y, x)
. Points and images are always returned as images, and multiscale raster data is always returned as single-scale data.agg_func (
Union
[str
,Reduction
,None
] (default:None
)) – Available only when rasterizing points and shapes. A reduction function from datashader (its name, or aCallable
). See the notes for more details on the default behavior. Must beNone
whendata
is aSpatialData
object.return_single_channel (
Optional
[bool
] (default:None
)) – Only used when rasterizing points and shapes and whenvalue_key
refers to a categorical column. IfFalse
, each category will be rasterized in a separate channel.
- Return type:
- Returns:
: The rasterized
SpatialData
object or SpatialData supportedDataArray
. EachSpatialElement
will be rasterized into aDataArray
(not aDataTree
). So if aSpatialData
object with elements is passed, aSpatialData
object with single-scale images and labels will be returned.
Notes
For images and labels, the parameters
value_key
,table_name
,agg_func
, andreturn_single_channel
are not used.Instead, when rasterizing shapes and points, the following table clarifies the default datashader reduction used for various combinations of parameters.
In particular, the first two rows refer to the default behavior when the parameters (
value_key
, ‘table_name’,returned_single_channel
,agg_func
) are kept to their default values.value_key
Shapes or Points
return_single_chan
datashader reduct.
table_name
None*
Point (default)
NA
count
‘table’
None**
Shapes (default)
True
first
‘table’
None**
Shapes
False
count_cat
‘table’
category
NA
True
first
‘table’
category
NA
False
count_cat
‘table’
int/float
NA
NA
sum
‘table’
Explicitly, the default behaviors are as follows.
for points, each pixel counts the number of points belonging to it, (the
count
function is applied to an artificial column of ones);for shapes, each pixel gets a single index among the ones of the shapes that intersect it (the index of the shapes is interpreted as a categorical column and then the
first
function is used).