swap combine kw to collapse (#424)

* swap combine kw to collapse

* use collapse in tests

Author: rafaqz

src/methods/mask.jl

@@ -15,12 +15,6 @@ const CRS_KEYWORD = """
 - `crs`: a `crs` which will be attached to the resulting raster when `to` not passed
    or is an `Extent`. Otherwise the crs from `to` is used.
 """
-const COMBINE_KEYWORD = """
-- `combine`: combine all geometries in tables/iterables into a single layer, or return
-    a `Raster` with a `:geometry` dimension where each slice is the rasterisation 
-    of a single geometry. This can be useful for reductions. Note the returned object
-    may be quite large when `combine=false`. `true` by default.
-"""
 
 const SHAPE_KEYWORDS = """
 - `shape`: Force `data` to be treated as `:polygon`, `:line` or `:point` geometries.
@@ -36,7 +30,6 @@ $RES_KEYWORD
 $SIZE_KEYWORD
 $CRS_KEYWORD
 $SHAPE_KEYWORDS
-$COMBINE_KEYWORD
 """
 
 
@@ -260,7 +253,7 @@ And specifically for `shape=:polygon`:
 
 For tabular data, feature collections and other iterables
 
-- `combine`: if `true`, combine all objects into a single mask. Otherwise
+- `collapse`: if `true`, collapse all geometry masks into a single mask. Otherwise
     return a Raster with an additional `geometry` dimension, so that each slice
     along this axis is the mask of the `geometry` opbject of each row of the
     table, feature in the feature collection, or just each geometry in the iterable.
@@ -327,7 +320,7 @@ end
 
 """
     missingmask(obj::Raster; kw...)
-    missingmask(obj; [to, res, size, combine])
+    missingmask(obj; [to, res, size, collapse])
 
 Create a mask array of `missing` and `true` values, from another `Raster`.
 `AbstractRasterStack` or `AbstractRasterSeries` are also accepted, but a mask

src/methods/rasterize.jl

@@ -359,7 +359,7 @@ function _rasterize_iterable!(
     kw...
 )
     # We dont need to iterate the fill, so just mask
-    mask = boolmask(geoms; to=x1, combine=true, allocs=thread_allocs, metadata=metadata(x1), kw...)
+    mask = boolmask(geoms; to=x1, collapse=true, allocs=thread_allocs, metadata=metadata(x1), kw...)
     # And broadcast the fill
     broadcast_dims!(x1, x1, mask) do v, m
         m ? fill_itr.xs : v
@@ -372,7 +372,7 @@ function _rasterize_iterable!(
     kw...
 )
     # We dont need to iterate the fill, so just mask
-    mask = boolmask(geoms; to=x1, combine=true, allocs=thread_allocs, metadata=metadata(x1), kw...)
+    mask = boolmask(geoms; to=x1, collapse=true, allocs=thread_allocs, metadata=metadata(x1), kw...)
     foreach(x1, fill_itr) do A, f 
         # And broadcast the fill
         broadcast_dims!(A, A, mask) do v, m
@@ -456,7 +456,7 @@ function _reduce_fill!(f, st::AbstractRasterStack, geoms, fill_itr::NamedTuple;
     # Define mask dimensions, the same size as the spatial dims of x
     spatialdims = commondims(st, DEFAULT_POINT_ORDER)
     # Mask geoms as separate bool layers
-    masks = boolmask(geoms; to=st, combine=false, metadata=metadata(st), kw...)
+    masks = boolmask(geoms; to=st, collapse=false, metadata=metadata(st), kw...)
     # Use a generator over the array axis in case the iterator has no length
     geom_axis = axes(masks, Dim{:geometry}())
     fill = map(itr -> [v for (_, v) in zip(geom_axis, itr)], fill_itr)
@@ -467,7 +467,7 @@ function _reduce_fill!(f, A::AbstractRaster, geoms, fill_itr; progress=true, kw.
     # Define mask dimensions, the same size as the spatial dims of x
     spatialdims = commondims(A, DEFAULT_POINT_ORDER)
     # Mask geoms as separate bool layers
-    masks = boolmask(geoms; to=A, combine=false, metadata=metadata(A), kw...)
+    masks = boolmask(geoms; to=A, collapse=false, metadata=metadata(A), kw...)
     # Use a generator over the array axis in case the iterator has no length
     geom_axis = parent(axes(masks, Dim{:geometry}()))
     fill = [val for (i, val) in zip(geom_axis, fill_itr)]

src/polygon_ops.jl

@@ -175,14 +175,14 @@ function _burn_geometry!(B::AbstractRaster, ::GI.AbstractFeatureCollectionTrait,
 end
 # Where geoms is an iterator
 function _burn_geometry!(B::AbstractRaster, trait::Nothing, geoms; 
-    combine::Union{Bool,Nothing}=nothing, lock=SectorLocks(), verbose=true, progress=true, kw...
+    collapse::Union{Bool,Nothing}=nothing, lock=SectorLocks(), verbose=true, progress=true, kw...
 )::Bool
     thread_allocs = _burning_allocs(B) 
     range = _geomindices(geoms)
     checklock = Threads.SpinLock()
     burnchecks = _alloc_burnchecks(range)
     p = progress ? _progress(length(range)) : nothing
-    if isnothing(combine) || combine
+    if isnothing(collapse) || collapse
         Threads.@threads for i in range
             geom = _getgeom(geoms, i)
             ismissing(geom) && continue
@@ -746,8 +746,8 @@ function _init_bools(to::Nothing, T::Type, data; kw...)
     dims = _extent2dims(ext; kw...)
     return _init_bools(to, dims, T, data; kw...)
 end
-function _init_bools(to, dims::DimTuple, T::Type, data; combine::Union{Bool,Nothing}=nothing, kw...)
-    if isnothing(data) || isnothing(combine) || combine
+function _init_bools(to, dims::DimTuple, T::Type, data; collapse::Union{Bool,Nothing}=nothing, kw...)
+    if isnothing(data) || isnothing(collapse) || collapse
         _alloc_bools(to, dims, T; kw...)
     else
         n = if Base.IteratorSize(data) isa Base.HasShape

test/methods.jl

@@ -73,12 +73,12 @@ end
     @test x == trues(X(Projected(-20:1.0:-1.0; crs=nothing)), Y(Projected(10.0:1.0:29.0; crs=nothing)))
     @test parent(x) isa BitArray{2}
     # With a :geometry axis
-    x = boolmask([polygon, polygon]; combine=false, res=1.0)
+    x = boolmask([polygon, polygon]; collapse=false, res=1.0)
     @test eltype(x) == Bool
     @test size(x) == (20, 20, 2)
     @test sum(x) == 800
     @test parent(x) isa BitArray{3}
-    x = boolmask([polygon, polygon]; combine=true, res=1.0)
+    x = boolmask([polygon, polygon]; collapse=true, res=1.0)
     @test size(x) == (20, 20)
     @test sum(x) == 400
     @test parent(x) isa BitArray{2}
@@ -90,12 +90,12 @@ end
     @test all(missingmask(gaNaN) .=== [missing true; true missing])
     @test dims(missingmask(ga)) == (X(NoLookup(Base.OneTo(2))), Y(NoLookup(Base.OneTo(2))))
     @test missingmask(polygon; res=1.0) == fill!(Raster{Union{Missing,Bool}}(undef, X(Projected(-20:1.0:-1.0; crs=nothing)), Y(Projected(10.0:1.0:29.0; crs=nothing))), true)
-    x = missingmask([polygon, polygon]; combine=false, res=1.0)
+    x = missingmask([polygon, polygon]; collapse=false, res=1.0)
     @test eltype(x) == Union{Bool,Missing}
     @test size(x) == (20, 20, 2)
     @test sum(x) == 800
     @test parent(x) isa Array{Union{Missing,Bool},3}
-    x = missingmask([polygon, polygon]; combine=true, res=1.0)
+    x = missingmask([polygon, polygon]; collapse=true, res=1.0)
     @test size(x) == (20, 20)
     @test sum(x) == 400
 end