Repository navigation
Expand file tree
/
Copy pathcore.py
More file actions
1446 lines (1267 loc) · 60.6 KB
/
Copy pathcore.py
File metadata and controls
1446 lines (1267 loc) · 60.6 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
from __future__ import annotations
from numbers import Number
from math import log10
import warnings
import contextlib
import numpy as np
import pandas as pd
from packaging.version import Version
from xarray import DataArray, Dataset
from .utils import Dispatcher, ngjit, calc_res, calc_bbox, orient_array, \
dshape_from_xarray_dataset
from .utils import get_indices, dshape_from_pandas, dshape_from_dask
from .utils import Expr # noqa (API import)
from .resampling import resample_2d, resample_2d_distributed
from . import reductions as rd
try:
import dask.dataframe as dd
except ImportError:
dd = None
try:
import dask.array as da
except ImportError:
da = None
try:
import cudf
except Exception:
cudf = None
try:
import dask_cudf
except Exception:
dask_cudf = None
try:
import spatialpandas
except Exception:
spatialpandas = None
class Axis:
"""Interface for implementing axis transformations.
Instances hold implementations of transformations to and from axis space.
The default implementation is equivalent to:
>>> def forward_transform(data_x):
... scale * mapper(data_x) + t
>>> def inverse_transform(axis_x):
... inverse_mapper((axis_x - t)/s)
Where ``mapper`` and ``inverse_mapper`` are elementwise functions mapping
to and from axis-space respectively, and ``scale`` and ``transform`` are
parameters describing a linear scale and translate transformation, computed
by the ``compute_scale_and_translate`` method.
"""
def compute_scale_and_translate(self, range, n):
"""Compute the scale and translate parameters for a linear transformation
``output = s * input + t``, mapping from data space to axis space.
Parameters
----------
range : tuple
A tuple representing the range ``[min, max]`` along the axis, in
data space. Both min and max are inclusive.
n : int
The number of bins along the axis.
Returns
-------
s, t : floats
"""
start, end = map(self.mapper, range)
s = n/(end - start)
t = -start * s
return s, t
def compute_index(self, st, n):
"""Compute a 1D array representing the axis index.
Parameters
----------
st : tuple
A tuple of ``(scale, translate)`` parameters.
n : int
The number of bins along the dimension.
Returns
-------
index : ndarray
"""
px = np.arange(n)+0.5
s, t = st
return self.inverse_mapper((px - t)/s)
def mapper(val):
"""A mapping from data space to axis space"""
raise NotImplementedError
def inverse_mapper(val):
"""A mapping from axis space to data space"""
raise NotImplementedError
def validate(self, range):
"""Given a range (low,high), raise an error if the range is invalid for this axis"""
pass
class LinearAxis(Axis):
"""A linear Axis"""
@staticmethod
@ngjit
def mapper(val):
return val
@staticmethod
@ngjit
def inverse_mapper(val):
return val
class LogAxis(Axis):
"""A base-10 logarithmic Axis"""
@staticmethod
@ngjit
def mapper(val):
return log10(float(val))
@staticmethod
@ngjit
def inverse_mapper(val):
y = 10 # temporary workaround for https://github.com/numba/numba/issues/3135 (numba 0.39.0)
return y**val
def validate(self, range):
if range is None:
# Nothing to check if no range
return
if range[0] <= 0 or range[1] <= 0:
raise ValueError('Range values must be >0 for logarithmic axes')
_axis_lookup = {'linear': LinearAxis(), 'log': LogAxis()}
def validate_xy_or_geometry(glyph, x, y, geometry):
if (geometry is None and (x is None or y is None) or
geometry is not None and (x is not None or y is not None)):
raise ValueError(f"""
{glyph} coordinates may be specified by providing both the x and y arguments, or by
providing the geometry argument. Received:
x: {x!r}
y: {y!r}
geometry: {geometry!r}
""")
class Canvas:
"""An abstract canvas representing the space in which to bin.
Parameters
----------
plot_width, plot_height : int, optional
Width and height of the output aggregate in pixels.
x_range, y_range : tuple, optional
A tuple representing the bounds inclusive space ``[min, max]`` along
the axis.
x_axis_type, y_axis_type : str, optional
The type of the axis. Valid options are ``'linear'`` [default], and
``'log'``.
"""
def __init__(self, plot_width=600, plot_height=600,
x_range=None, y_range=None,
x_axis_type='linear', y_axis_type='linear'):
self.plot_width = plot_width
self.plot_height = plot_height
self.x_range = None if x_range is None else tuple(x_range)
self.y_range = None if y_range is None else tuple(y_range)
self.x_axis = _axis_lookup[x_axis_type]
self.y_axis = _axis_lookup[y_axis_type]
def points(self, source, x=None, y=None, agg=None, geometry=None):
"""Compute a reduction by pixel, mapping data to pixels as points.
Parameters
----------
source : pandas.DataFrame, dask.DataFrame, or xarray.DataArray/Dataset
The input datasource.
x, y : str
Column names for the x and y coordinates of each point. If provided,
the geometry argument may not also be provided.
agg : Reduction, optional
Reduction to compute. Default is ``count()``.
geometry: str
Column name of a PointsArray of the coordinates of each point. If provided,
the x and y arguments may not also be provided.
"""
from .glyphs import Point, MultiPointGeometry
from .reductions import count as count_rdn
validate_xy_or_geometry('Point', x, y, geometry)
if agg is None:
agg = count_rdn()
if geometry is None:
glyph = Point(x, y)
else:
if spatialpandas and isinstance(source, spatialpandas.dask.DaskGeoDataFrame):
# Downselect partitions to those that may contain points in viewport
x_range = self.x_range if self.x_range is not None else (None, None)
y_range = self.y_range if self.y_range is not None else (None, None)
source = source.cx_partitions[slice(*x_range), slice(*y_range)]
glyph = MultiPointGeometry(geometry)
elif spatialpandas and isinstance(source, spatialpandas.GeoDataFrame):
glyph = MultiPointGeometry(geometry)
elif (geopandas_source := self._source_from_geopandas(source)) is not None:
source = geopandas_source
from datashader.glyphs.points import MultiPointGeoPandas
glyph = MultiPointGeoPandas(geometry)
else:
raise ValueError(
"source must be an instance of spatialpandas.GeoDataFrame, "
"spatialpandas.dask.DaskGeoDataFrame, geopandas.GeoDataFrame, or "
f"dask_geopandas.GeoDataFrame. Received objects of type {type(source)}")
return bypixel(source, self, glyph, agg)
def line(self, source, x=None, y=None, agg=None, axis=0, geometry=None,
line_width=0, antialias=False):
"""Compute a reduction by pixel, mapping data to pixels as one or
more lines.
For aggregates that take in extra fields, the interpolated bins will
receive the fields from the previous point. In pseudocode:
>>> for i in range(len(rows) - 1): # doctest: +SKIP
... row0 = rows[i]
... row1 = rows[i + 1]
... for xi, yi in interpolate(row0.x, row0.y, row1.x, row1.y):
... add_to_aggregate(xi, yi, row0)
Parameters
----------
source : pandas.DataFrame, dask.DataFrame, or xarray.DataArray/Dataset
The input datasource.
x, y : str or number or list or tuple or np.ndarray
Specification of the x and y coordinates of each vertex
* str or number: Column labels in source
* list or tuple: List or tuple of column labels in source
* np.ndarray: When axis=1, a literal array of the
coordinates to be used for every row
agg : Reduction, optional
Reduction to compute. Default is ``any()``.
axis : 0 or 1, default 0
Axis in source to draw lines along
* 0: Draw lines using data from the specified columns across
all rows in source
* 1: Draw one line per row in source using data from the
specified columns
geometry : str
Column name of a LinesArray of the coordinates of each line. If provided,
the x and y arguments may not also be provided.
line_width : number, optional
Width of the line to draw, in pixels. If zero, the
default, lines are drawn using a simple algorithm with a
blocky single-pixel width based on whether the line passes
through each pixel or does not. If greater than one, lines
are drawn with the specified width using a slower and
more complex antialiasing algorithm with fractional values
along each edge, so that lines have a more uniform visual
appearance across all angles. Line widths between 0 and 1
effectively use a line_width of 1 pixel but with a
proportionate reduction in the strength of each pixel,
approximating the visual appearance of a subpixel line
width.
antialias : bool, optional
This option is kept for backward compatibility only.
``True`` is equivalent to ``line_width=1`` and
``False`` (the default) to ``line_width=0``. Do not specify
both ``antialias`` and ``line_width`` in the same call as a
``ValueError`` will be raised if they disagree.
Examples
--------
Define a canvas and a pandas DataFrame with 6 rows
>>> import pandas as pd # doctest: +SKIP
... import numpy as np
... import datashader as ds
... from datashader import Canvas
... import datashader.transfer_functions as tf
... cvs = Canvas()
... df = pd.DataFrame({
... 'A1': [1, 1.5, 2, 2.5, 3, 4],
... 'A2': [1.5, 2, 3, 3.2, 4, 5],
... 'B1': [10, 12, 11, 14, 13, 15],
... 'B2': [11, 9, 10, 7, 8, 12],
... }, dtype='float64')
Aggregate one line across all rows, with coordinates df.A1 by df.B1
>>> agg = cvs.line(df, x='A1', y='B1', axis=0) # doctest: +SKIP
... tf.spread(tf.shade(agg))
Aggregate two lines across all rows. The first with coordinates
df.A1 by df.B1 and the second with coordinates df.A2 by df.B2
>>> agg = cvs.line(df, x=['A1', 'A2'], y=['B1', 'B2'], axis=0) # doctest: +SKIP
... tf.spread(tf.shade(agg))
Aggregate two lines across all rows where the lines share the same
x coordinates. The first line will have coordinates df.A1 by df.B1
and the second will have coordinates df.A1 by df.B2
>>> agg = cvs.line(df, x='A1', y=['B1', 'B2'], axis=0) # doctest: +SKIP
... tf.spread(tf.shade(agg))
Aggregate 6 length-2 lines, one per row, where the ith line has
coordinates [df.A1[i], df.A2[i]] by [df.B1[i], df.B2[i]]
>>> agg = cvs.line(df, x=['A1', 'A2'], y=['B1', 'B2'], axis=1) # doctest: +SKIP
... tf.spread(tf.shade(agg))
Aggregate 6 length-4 lines, one per row, where the x coordinates
of every line are [0, 1, 2, 3] and the y coordinates of the ith line
are [df.A1[i], df.A2[i], df.B1[i], df.B2[i]].
>>> agg = cvs.line(df, # doctest: +SKIP
... x=np.arange(4),
... y=['A1', 'A2', 'B1', 'B2'],
... axis=1)
... tf.spread(tf.shade(agg))
Aggregate RaggedArrays of variable length lines, one per row
(requires pandas >= 0.24.0)
>>> df_ragged = pd.DataFrame({ # doctest: +SKIP
... 'A1': pd.array([
... [1, 1.5], [2, 2.5, 3], [1.5, 2, 3, 4], [3.2, 4, 5]],
... dtype='Ragged[float32]'),
... 'B1': pd.array([
... [10, 12], [11, 14, 13], [10, 7, 9, 10], [7, 8, 12]],
... dtype='Ragged[float32]'),
... 'group': pd.Categorical([0, 1, 2, 1])
... })
...
... agg = cvs.line(df_ragged, x='A1', y='B1', axis=1)
... tf.spread(tf.shade(agg))
Aggregate RaggedArrays of variable length lines by group column,
one per row (requires pandas >= 0.24.0)
>>> agg = cvs.line(df_ragged, x='A1', y='B1', # doctest: +SKIP
... agg=ds.count_cat('group'), axis=1)
... tf.spread(tf.shade(agg))
"""
from .glyphs import (LineAxis0, LinesAxis1, LinesAxis1XConstant,
LinesAxis1YConstant, LineAxis0Multi,
LinesAxis1Ragged, LineAxis1Geometry, LinesXarrayCommonX)
validate_xy_or_geometry('Line', x, y, geometry)
if agg is None:
agg = rd.any()
if line_width is None:
line_width = 0
# Check and convert antialias kwarg to line_width.
if antialias and line_width != 0:
raise ValueError(
"Do not specify values for both the line_width and \n"
"antialias keyword arguments; use line_width instead.")
if antialias:
line_width = 1.0
if geometry is not None:
if spatialpandas and isinstance(source, spatialpandas.dask.DaskGeoDataFrame):
# Downselect partitions to those that may contain lines in viewport
x_range = self.x_range if self.x_range is not None else (None, None)
y_range = self.y_range if self.y_range is not None else (None, None)
source = source.cx_partitions[slice(*x_range), slice(*y_range)]
glyph = LineAxis1Geometry(geometry)
elif spatialpandas and isinstance(source, spatialpandas.GeoDataFrame):
glyph = LineAxis1Geometry(geometry)
elif (geopandas_source := self._source_from_geopandas(source)) is not None:
source = geopandas_source
from datashader.glyphs.line import LineAxis1GeoPandas
glyph = LineAxis1GeoPandas(geometry)
else:
raise ValueError(
"source must be an instance of spatialpandas.GeoDataFrame, "
"spatialpandas.dask.DaskGeoDataFrame, geopandas.GeoDataFrame, or "
f"dask_geopandas.GeoDataFrame. Received objects of type {type(source)}")
elif isinstance(source, Dataset) and isinstance(x, str) and isinstance(y, str):
x_arr = source[x]
y_arr = source[y]
if x_arr.ndim != 1:
raise ValueError(f"x array must have 1 dimension not {x_arr.ndim}")
if y_arr.ndim != 2:
raise ValueError(f"y array must have 2 dimensions not {y_arr.ndim}")
if x not in y_arr.dims:
raise ValueError("x must be one of the coordinate dimensions of y")
y_coord_dims = list(y_arr.coords.dims)
x_dim_index = y_coord_dims.index(x)
glyph = LinesXarrayCommonX(x, y, x_dim_index)
else:
# Broadcast column specifications to handle cases where
# x is a list and y is a string or vice versa
orig_x, orig_y = x, y
x, y = _broadcast_column_specifications(x, y)
if axis == 0:
if (isinstance(x, (Number, str)) and
isinstance(y, (Number, str))):
glyph = LineAxis0(x, y)
elif (isinstance(x, (list, tuple)) and
isinstance(y, (list, tuple))):
glyph = LineAxis0Multi(tuple(x), tuple(y))
else:
raise ValueError(f"""
Invalid combination of x and y arguments to Canvas.line when axis=0.
Received:
x: {repr(orig_x)}
y: {repr(orig_y)}
See docstring for more information on valid usage""")
elif axis == 1:
if isinstance(x, (list, tuple)) and isinstance(y, (list, tuple)):
glyph = LinesAxis1(tuple(x), tuple(y))
elif (isinstance(x, np.ndarray) and
isinstance(y, (list, tuple))):
glyph = LinesAxis1XConstant(x, tuple(y))
elif (isinstance(x, (list, tuple)) and
isinstance(y, np.ndarray)):
glyph = LinesAxis1YConstant(tuple(x), y)
elif (isinstance(x, (Number, str)) and
isinstance(y, (Number, str))):
glyph = LinesAxis1Ragged(x, y)
else:
raise ValueError(f"""
Invalid combination of x and y arguments to Canvas.line when axis=1.
Received:
x: {repr(orig_x)}
y: {repr(orig_y)}
See docstring for more information on valid usage""")
else:
raise ValueError(f"""
The axis argument to Canvas.line must be 0 or 1
Received: {axis}""")
if (line_width > 0 and ((cudf and isinstance(source, cudf.DataFrame)) or
(dask_cudf and isinstance(source, dask_cudf.DataFrame)))):
warnings.warn(
"Antialiased lines are not supported for CUDA-backed sources, "
"so reverting to line_width=0")
line_width = 0
glyph.set_line_width(line_width)
if glyph.antialiased:
# This is required to identify and report use of reductions that do
# not yet support antialiasing.
non_cat_agg = agg
if isinstance(non_cat_agg, rd.by):
non_cat_agg = non_cat_agg.reduction
if not isinstance(non_cat_agg, (
rd.any, rd.count, rd.max, rd.min, rd.sum, rd.summary, rd._sum_zero,
rd._first_or_last, rd.mean, rd.max_n, rd.min_n, rd._first_n_or_last_n,
rd._max_or_min_row_index, rd._max_n_or_min_n_row_index, rd.where,
)):
raise NotImplementedError(
f"{type(non_cat_agg)} reduction not implemented for antialiased lines")
return bypixel(source, self, glyph, agg, antialias=glyph.antialiased)
def area(self, source, x, y, agg=None, axis=0, y_stack=None):
"""Compute a reduction by pixel, mapping data to pixels as a filled
area region
Parameters
----------
source : pandas.DataFrame, dask.DataFrame, or xarray.DataArray/Dataset
The input datasource.
x, y : str or number or list or tuple or np.ndarray
Specification of the x and y coordinates of each vertex of the
line defining the starting edge of the area region.
* str or number: Column labels in source
* list or tuple: List or tuple of column labels in source
* np.ndarray: When axis=1, a literal array of the
coordinates to be used for every row
agg : Reduction, optional
Reduction to compute. Default is ``count()``.
axis : 0 or 1, default 0
Axis in source to draw lines along
* 0: Draw area regions using data from the specified columns
across all rows in source
* 1: Draw one area region per row in source using data from the
specified columns
y_stack: str or number or list or tuple or np.ndarray or None
Specification of the y coordinates of each vertex of the line
defining the ending edge of the area region, where the x
coordinate is given by the x argument described above.
If y_stack is None, then the area region is filled to the y=0 line
If y_stack is not None, then the form of y_stack must match the
form of y.
Examples
--------
Define a canvas and a pandas DataFrame with 6 rows
>>> import pandas as pd # doctest: +SKIP
... import numpy as np
... import datashader as ds
... from datashader import Canvas
... import datashader.transfer_functions as tf
... cvs = Canvas()
... df = pd.DataFrame({
... 'A1': [1, 1.5, 2, 2.5, 3, 4],
... 'A2': [1.6, 2.1, 2.9, 3.2, 4.2, 5],
... 'B1': [10, 12, 11, 14, 13, 15],
... 'B2': [11, 9, 10, 7, 8, 12],
... }, dtype='float64')
Aggregate one area region across all rows, that starts with
coordinates df.A1 by df.B1 and is filled to the y=0 line
>>> agg = cvs.area(df, x='A1', y='B1', # doctest: +SKIP
... agg=ds.count(), axis=0)
... tf.shade(agg)
Aggregate one area region across all rows, that starts with
coordinates df.A1 by df.B1 and is filled to the line with coordinates
df.A1 by df.B2
>>> agg = cvs.area(df, x='A1', y='B1', y_stack='B2', # doctest: +SKIP
... agg=ds.count(), axis=0)
... tf.shade(agg)
Aggregate two area regions across all rows. The first starting
with coordinates df.A1 by df.B1 and the second with coordinates
df.A2 by df.B2. Both regions are filled to the y=0 line
>>> agg = cvs.area(df, x=['A1', 'A2'], y=['B1', 'B2'], # doctest: +SKIP
agg=ds.count(), axis=0)
... tf.shade(agg)
Aggregate two area regions across all rows where the regions share the
same x coordinates. The first region will start with coordinates
df.A1 by df.B1 and the second will start with coordinates
df.A1 by df.B2. Both regions are filled to the y=0 line
>>> agg = cvs.area(df, x='A1', y=['B1', 'B2'], agg=ds.count(), axis=0) # doctest: +SKIP
... tf.shade(agg)
Aggregate 6 length-2 area regions, one per row, where the ith region
starts with coordinates [df.A1[i], df.A2[i]] by [df.B1[i], df.B2[i]]
and is filled to the y=0 line
>>> agg = cvs.area(df, x=['A1', 'A2'], y=['B1', 'B2'], # doctest: +SKIP
agg=ds.count(), axis=1)
... tf.shade(agg)
Aggregate 6 length-4 area regions, one per row, where the
starting x coordinates of every region are [0, 1, 2, 3] and
the starting y coordinates of the ith region are
[df.A1[i], df.A2[i], df.B1[i], df.B2[i]]. All regions are filled to
the y=0 line
>>> agg = cvs.area(df, # doctest: +SKIP
... x=np.arange(4),
... y=['A1', 'A2', 'B1', 'B2'],
... agg=ds.count(),
... axis=1)
... tf.shade(agg)
Aggregate RaggedArrays of variable length area regions, one per row.
The starting coordinates of the ith region are df_ragged.A1 by
df_ragged.B1 and the regions are filled to the y=0 line.
(requires pandas >= 0.24.0)
>>> df_ragged = pd.DataFrame({ # doctest: +SKIP
... 'A1': pd.array([
... [1, 1.5], [2, 2.5, 3], [1.5, 2, 3, 4], [3.2, 4, 5]],
... dtype='Ragged[float32]'),
... 'B1': pd.array([
... [10, 12], [11, 14, 13], [10, 7, 9, 10], [7, 8, 12]],
... dtype='Ragged[float32]'),
... 'B2': pd.array([
... [6, 10], [9, 10, 18], [9, 5, 6, 8], [4, 5, 11]],
... dtype='Ragged[float32]'),
... 'group': pd.Categorical([0, 1, 2, 1])
... })
...
... agg = cvs.area(df_ragged, x='A1', y='B1', agg=ds.count(), axis=1)
... tf.shade(agg)
Instead of filling regions to the y=0 line, fill to the line with
coordinates df_ragged.A1 by df_ragged.B2
>>> agg = cvs.area(df_ragged, x='A1', y='B1', y_stack='B2', # doctest: +SKIP
... agg=ds.count(), axis=1)
... tf.shade(agg)
(requires pandas >= 0.24.0)
"""
from .glyphs import (
AreaToZeroAxis0, AreaToLineAxis0,
AreaToZeroAxis0Multi, AreaToLineAxis0Multi,
AreaToZeroAxis1, AreaToLineAxis1,
AreaToZeroAxis1XConstant, AreaToLineAxis1XConstant,
AreaToZeroAxis1YConstant, AreaToLineAxis1YConstant,
AreaToZeroAxis1Ragged, AreaToLineAxis1Ragged,
)
from .reductions import any as any_rdn
if agg is None:
agg = any_rdn()
# Broadcast column specifications to handle cases where
# x is a list and y is a string or vice versa
orig_x, orig_y, orig_y_stack = x, y, y_stack
x, y, y_stack = _broadcast_column_specifications(x, y, y_stack)
if axis == 0:
if y_stack is None:
if (isinstance(x, (Number, str)) and
isinstance(y, (Number, str))):
glyph = AreaToZeroAxis0(x, y)
elif (isinstance(x, (list, tuple)) and
isinstance(y, (list, tuple))):
glyph = AreaToZeroAxis0Multi(tuple(x), tuple(y))
else:
raise ValueError(f"""
Invalid combination of x and y arguments to Canvas.area when axis=0.
Received:
x: {repr(x)}
y: {repr(y)}
See docstring for more information on valid usage""")
else:
# y_stack is not None
if (isinstance(x, (Number, str)) and
isinstance(y, (Number, str)) and
isinstance(y_stack, (Number, str))):
glyph = AreaToLineAxis0(x, y, y_stack)
elif (isinstance(x, (list, tuple)) and
isinstance(y, (list, tuple)) and
isinstance(y_stack, (list, tuple))):
glyph = AreaToLineAxis0Multi(
tuple(x), tuple(y), tuple(y_stack))
else:
raise ValueError(f"""
Invalid combination of x, y, and y_stack arguments to Canvas.area when axis=0.
Received:
x: {repr(orig_x)}
y: {repr(orig_y)}
y_stack: {repr(orig_y_stack)}
See docstring for more information on valid usage""")
elif axis == 1:
if y_stack is None:
if (isinstance(x, (list, tuple)) and
isinstance(y, (list, tuple))):
glyph = AreaToZeroAxis1(tuple(x), tuple(y))
elif (isinstance(x, np.ndarray) and
isinstance(y, (list, tuple))):
glyph = AreaToZeroAxis1XConstant(x, tuple(y))
elif (isinstance(x, (list, tuple)) and
isinstance(y, np.ndarray)):
glyph = AreaToZeroAxis1YConstant(tuple(x), y)
elif (isinstance(x, (Number, str)) and
isinstance(y, (Number, str))):
glyph = AreaToZeroAxis1Ragged(x, y)
else:
raise ValueError(f"""
Invalid combination of x and y arguments to Canvas.area when axis=1.
Received:
x: {repr(x)}
y: {repr(y)}
See docstring for more information on valid usage""")
else:
if (isinstance(x, (list, tuple)) and
isinstance(y, (list, tuple)) and
isinstance(y_stack, (list, tuple))):
glyph = AreaToLineAxis1(
tuple(x), tuple(y), tuple(y_stack))
elif (isinstance(x, np.ndarray) and
isinstance(y, (list, tuple)) and
isinstance(y_stack, (list, tuple))):
glyph = AreaToLineAxis1XConstant(
x, tuple(y), tuple(y_stack))
elif (isinstance(x, (list, tuple)) and
isinstance(y, np.ndarray) and
isinstance(y_stack, np.ndarray)):
glyph = AreaToLineAxis1YConstant(tuple(x), y, y_stack)
elif (isinstance(x, (Number, str)) and
isinstance(y, (Number, str)) and
isinstance(y_stack, (Number, str))):
glyph = AreaToLineAxis1Ragged(x, y, y_stack)
else:
raise ValueError(f"""
Invalid combination of x, y, and y_stack arguments to Canvas.area when axis=1.
Received:
x: {repr(orig_x)}
y: {repr(orig_y)}
y_stack: {repr(orig_y_stack)}
See docstring for more information on valid usage""")
else:
raise ValueError(f"""
The axis argument to Canvas.area must be 0 or 1
Received: {axis}""")
return bypixel(source, self, glyph, agg)
def polygons(self, source, geometry, agg=None):
"""Compute a reduction by pixel, mapping data to pixels as one or
more filled polygons.
Parameters
----------
source : xarray.DataArray or Dataset
The input datasource.
geometry : str
Column name of a PolygonsArray of the coordinates of each line.
agg : Reduction, optional
Reduction to compute. Default is ``any()``.
Returns
-------
data : xarray.DataArray
Examples
--------
>>> import datashader as ds # doctest: +SKIP
... import datashader.transfer_functions as tf
... from spatialpandas.geometry import PolygonArray
... from spatialpandas import GeoDataFrame
... import pandas as pd
...
... polygons = PolygonArray([
... # First Element
... [[0, 0, 1, 0, 2, 2, -1, 4, 0, 0], # Filled quadrilateral (CCW order)
... [0.5, 1, 1, 2, 1.5, 1.5, 0.5, 1], # Triangular hole (CW order)
... [0, 2, 0, 2.5, 0.5, 2.5, 0.5, 2, 0, 2], # Rectangular hole (CW order)
... [2.5, 3, 3.5, 3, 3.5, 4, 2.5, 3], # Filled triangle
... ],
...
... # Second Element
... [[3, 0, 3, 2, 4, 2, 4, 0, 3, 0], # Filled rectangle (CCW order)
... # Rectangular hole (CW order)
... [3.25, 0.25, 3.75, 0.25, 3.75, 1.75, 3.25, 1.75, 3.25, 0.25],
... ]
... ])
...
... df = GeoDataFrame({'polygons': polygons, 'v': range(len(polygons))})
...
... cvs = ds.Canvas()
... agg = cvs.polygons(df, geometry='polygons', agg=ds.sum('v'))
... tf.shade(agg)
"""
from .glyphs import PolygonGeom
from .reductions import any as any_rdn
if spatialpandas and isinstance(source, spatialpandas.dask.DaskGeoDataFrame):
# Downselect partitions to those that may contain polygons in viewport
x_range = self.x_range if self.x_range is not None else (None, None)
y_range = self.y_range if self.y_range is not None else (None, None)
source = source.cx_partitions[slice(*x_range), slice(*y_range)]
glyph = PolygonGeom(geometry)
elif spatialpandas and isinstance(source, spatialpandas.GeoDataFrame):
glyph = PolygonGeom(geometry)
elif (geopandas_source := self._source_from_geopandas(source)) is not None:
source = geopandas_source
from .glyphs.polygon import GeopandasPolygonGeom
glyph = GeopandasPolygonGeom(geometry)
else:
raise ValueError(
"source must be an instance of spatialpandas.GeoDataFrame, "
"spatialpandas.dask.DaskGeoDataFrame, geopandas.GeoDataFrame or "
f"dask_geopandas.GeoDataFrame, not {type(source)}")
if agg is None:
agg = any_rdn()
return bypixel(source, self, glyph, agg)
def quadmesh(self, source, x=None, y=None, agg=None):
r"""Samples a raster, rectilinear or curvilinear quadmesh by canvas size and bounds.
+---------------------+---------------------+---------------------+
| RASTER | RECTILINEAR | CURVILINEAR |
+---------------------+---------------------+---------------------+
| Regular spacing | Variable spacing | Variable 2D spacing |
| o---o---o---o---o | o-o---o----o-o | o---o---o---o |
| | | | | | | | | | | | | / / / / |
| o---o---o---o---o | o-o---o----o-o | o----o--o---o |
| | | | | | | | | | | | | / / / / |
| o---o---o---o---o | o-o---o----o-o | o--o----o---o |
| | | | | | | | | | | | | \ \ \ \ |
| o---o---o---o---o | o-o---o----o-o | o---o---o---o |
| `dx = dy = constant` | `dx` & `dy` vary in 1D | `dx` & `dy` vary in 2D |
| `x[i] = i * dx` | `x[i], y[j]` | `x[i,j], y[i,j]` |
| `y[j] = j * dy` | | |
+---------------------+---------------------+---------------------+
Parameters
----------
source : xarray.DataArray or Dataset
The input datasource.
x, y : str
Column names for the x and y coordinates of each point.
agg : Reduction, optional
Reduction to compute. Default is ``mean()``. Note that agg is ignored when
upsampling.
Returns
-------
data : xarray.DataArray
Note
----
Table from EarthMover
"""
from .glyphs import QuadMeshRaster, QuadMeshRectilinear, QuadMeshCurvilinear
from .reductions import mean as mean_rnd
if isinstance(source, Dataset):
if agg is None or agg.column is None:
name = list(source.data_vars)[0]
else:
name = agg.column
# Keep as dataset so that source[agg.column] works
source = source[[name]]
elif isinstance(source, DataArray):
# Make dataset so that source[agg.column] works
name = source.name
source = source.to_dataset()
else:
raise ValueError("Invalid input type")
if agg is None:
agg = mean_rnd(name)
if x is None and y is None:
if len(source[name].dims) == 2:
y, x = source[name].dims
else:
raise ValueError("x and y must be specified if dims is not 2D.")
elif not x or not y:
raise ValueError("Either specify both x and y coordinates"
"or allow them to be inferred.")
yarr, xarr = source[y], source[x]
if (yarr.ndim > 1 or xarr.ndim > 1) and xarr.dims != yarr.dims:
raise ValueError("Ensure that x- and y-coordinate arrays "
"share the same dimensions. x-coordinates "
f"are indexed by {xarr.dims} dims while "
f"y-coordinates are indexed by {yarr.dims} dims.")
if (name is not None
and agg.column is not None
and agg.column != name):
raise ValueError(f'DataArray name {source.name!r} does not match '
f'supplied reduction {agg}.')
if xarr.ndim == 1:
xaxis_linear = self.x_axis is _axis_lookup["linear"]
yaxis_linear = self.y_axis is _axis_lookup["linear"]
even_yspacing = np.allclose(
yarr, np.linspace(yarr[0].data, yarr[-1].data, len(yarr))
)
even_xspacing = np.allclose(
xarr, np.linspace(xarr[0].data, xarr[-1].data, len(xarr))
)
if xaxis_linear and yaxis_linear and even_xspacing and even_yspacing:
# Source is a raster, where all x and y coordinates are evenly spaced
glyph = QuadMeshRaster(x, y, name)
upsample_width, upsample_height = glyph.is_upsample(
source, x, y, name, self.x_range, self.y_range,
self.plot_width, self.plot_height
)
if upsample_width and upsample_height:
# Override aggregate with more efficient one for upsampling
agg = rd._upsample(name)
return bypixel(source, self, glyph, agg)
elif not upsample_width and not upsample_height:
# Downsample both width and height
return bypixel(source, self, glyph, agg)
else:
# Mix of upsampling and downsampling
# Use general rectilinear quadmesh implementation
glyph = QuadMeshRectilinear(x, y, name)
return bypixel(source, self, glyph, agg)
else:
# Source is a general rectilinear quadmesh
glyph = QuadMeshRectilinear(x, y, name)
return bypixel(source, self, glyph, agg)
elif xarr.ndim == 2:
glyph = QuadMeshCurvilinear(x, y, name)
return bypixel(source, self, glyph, agg)
else:
raise ValueError(f"""\
x- and y-coordinate arrays must have 1 or 2 dimensions.
Received arrays with dimensions: {list(xarr.dims)}""")
# TODO re 'untested', below: Consider replacing with e.g. a 3x3
# array in the call to Canvas (plot_height=3,plot_width=3), then
# show the output as a numpy array that has a compact
# representation
def trimesh(self, vertices, simplices, mesh=None, agg=None, interp=True, interpolate=None):
"""Compute a reduction by pixel, mapping data to pixels as a triangle.
>>> import datashader as ds
>>> verts = pd.DataFrame({'x': [0, 5, 10],
... 'y': [0, 10, 0],
... 'weight': [1, 5, 3]},
... columns=['x', 'y', 'weight'])
>>> tris = pd.DataFrame({'v0': [2], 'v1': [0], 'v2': [1]},
... columns=['v0', 'v1', 'v2'])
>>> cvs = ds.Canvas(x_range=(verts.x.min(), verts.x.max()),
... y_range=(verts.y.min(), verts.y.max()))
>>> untested = cvs.trimesh(verts, tris)
Parameters
----------
vertices : pandas.DataFrame, dask.DataFrame
The input datasource for triangle vertex coordinates. These can be
interpreted as the x/y coordinates of the vertices, with optional
weights for value interpolation. Columns should be ordered
corresponding to 'x', 'y', followed by zero or more (optional)
columns containing vertex values. The rows need not be ordered.
The column data types must be floating point or integer.
simplices : pandas.DataFrame, dask.DataFrame
The input datasource for triangle (simplex) definitions. These can
be interpreted as rows of ``vertices``, aka positions in the
``vertices`` index. Columns should be ordered corresponding to
'vertex0', 'vertex1', and 'vertex2'. Order of the vertices can be
clockwise or counter-clockwise; it does not matter as long as the
data is consistent for all simplices in the dataframe. The
rows need not be ordered. The data type for the first
three columns in the dataframe must be integer.
agg : Reduction, optional
Reduction to compute. Default is ``mean()``.
mesh : pandas.DataFrame, optional
An ordered triangle mesh in tabular form, used for optimization
purposes. This dataframe is expected to have come from
``datashader.utils.mesh()``. If this argument is not None, the first
two arguments are ignored.
interpolate : str, optional default=linear
Method to use for interpolation between specified values. ``nearest``
means to use a single value for the whole triangle, and ``linear``
means to do bilinear interpolation of the pixels within each
triangle (a weighted average of the vertex values). For
backwards compatibility, also accepts ``interp=True`` for ``linear``
and ``interp=False`` for ``nearest``.
"""
from .glyphs import Triangles
from .reductions import mean as mean_rdn
from .utils import mesh as create_mesh
source = mesh
# 'interp' argument is deprecated as of datashader=0.6.4
if interpolate is not None:
if interpolate == 'linear':
interp = True
elif interpolate == 'nearest':
interp = False
else:
raise ValueError('Invalid interpolate method: options include {}'.format(
['linear','nearest']))
# Validation is done inside the [pd]d_mesh utility functions
if source is None:
source = create_mesh(vertices, simplices)
verts_have_weights = len(vertices.columns) > 2
if verts_have_weights:
weight_col = vertices.columns[2]
else:
weight_col = simplices.columns[3]
if agg is None:
agg = mean_rdn(weight_col)
elif agg.column is None:
agg.column = weight_col
cols = source.columns
x, y, weights = cols[0], cols[1], cols[2:]
return bypixel(source, self, Triangles(x, y, weights, weight_type=verts_have_weights,
interp=interp), agg)
def raster(self,
source,
layer=None,
upsample_method='linear', # Deprecated as of datashader=0.6.4
downsample_method=rd.mean(), # Deprecated as of datashader=0.6.4
nan_value=None,
agg=None,
interpolate=None,
chunksize=None,
max_mem=None):
"""Sample a raster dataset by canvas size and bounds.