yirgacheffe 1.7.5__tar.gz → 1.7.6__tar.gz

{yirgacheffe-1.7.5/yirgacheffe.egg-info → yirgacheffe-1.7.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: yirgacheffe
-Version: 1.7.5
+Version: 1.7.6
 Summary: Abstraction of gdal datasets for doing basic math operations
 Author-email: Michael Dales <mwd24@cam.ac.uk>
 License-Expression: ISC
@@ -262,17 +262,33 @@ Notes:
 * You can have missing tiles, and these will be filled in with zeros.
 * You can have tiles that overlap, so long as they still conform to the rule that all tiles are the same size and on a grid.
 
-### ConstantLayer
+### Constants
 
-This is there to simplify code when you have some optional layers. Rather than littering your code with checks, you can just use a constant layer, which can be included in calculations and will just return an fixed value as if it wasn't there. Useful with 0.0 or 1.0 for sum or multiplication null layers.
+At times it is useful to have a fixed constant in an expression. Typically, similar to numpy, if an expression involving layers has a constant in, Yirgacheffe will apply that to all pixels in the equation without need for further elaboration:
+
+```python
+with yg.read_raster("some_data.tif") as layer:
+    doubled_layer = layer * 2.0
+    ...
+```
+
+This can be useful in tasks where you have an optional layer in your code. For example, here the code optionally loads an area-per-pixel layer, which if not present can just be substituted with a 1.0:
 
 ```python
 try:
-    area_layer = RasterLayer.layer_from_file('myarea.tiff')
+    area_layer = yg.read_raster('myarea.tiff')
 except FileDoesNotExist:
-    area_layer = ConstantLayer(0.0)
+    area_layer = 1.0
 ```
 
+However, as with numpy, Python can not make the correct inference if the constant value is the first term in the equation. In that case you need to explicitly wrap the value with `constant` to help Python understand what is happening:
+
+```python
+with yg.read_raster("some_data.tif") as layer:
+    result = yg.constant(1.0) / layer
+```
+
+
 ### H3CellLayer
 
 If you have H3 installed, you can generate a mask layer based on an H3 cell identifier, where pixels inside the cell will have a value of 1, and those outside will have a value of 0.

{yirgacheffe-1.7.5 → yirgacheffe-1.7.6}/README.md

@@ -232,17 +232,33 @@ Notes:
 * You can have missing tiles, and these will be filled in with zeros.
 * You can have tiles that overlap, so long as they still conform to the rule that all tiles are the same size and on a grid.
 
-### ConstantLayer
+### Constants
 
-This is there to simplify code when you have some optional layers. Rather than littering your code with checks, you can just use a constant layer, which can be included in calculations and will just return an fixed value as if it wasn't there. Useful with 0.0 or 1.0 for sum or multiplication null layers.
+At times it is useful to have a fixed constant in an expression. Typically, similar to numpy, if an expression involving layers has a constant in, Yirgacheffe will apply that to all pixels in the equation without need for further elaboration:
+
+```python
+with yg.read_raster("some_data.tif") as layer:
+    doubled_layer = layer * 2.0
+    ...
+```
+
+This can be useful in tasks where you have an optional layer in your code. For example, here the code optionally loads an area-per-pixel layer, which if not present can just be substituted with a 1.0:
 
 ```python
 try:
-    area_layer = RasterLayer.layer_from_file('myarea.tiff')
+    area_layer = yg.read_raster('myarea.tiff')
 except FileDoesNotExist:
-    area_layer = ConstantLayer(0.0)
+    area_layer = 1.0
 ```
 
+However, as with numpy, Python can not make the correct inference if the constant value is the first term in the equation. In that case you need to explicitly wrap the value with `constant` to help Python understand what is happening:
+
+```python
+with yg.read_raster("some_data.tif") as layer:
+    result = yg.constant(1.0) / layer
+```
+
+
 ### H3CellLayer
 
 If you have H3 installed, you can generate a mask layer based on an H3 cell identifier, where pixels inside the cell will have a value of 1, and those outside will have a value of 0.

{yirgacheffe-1.7.5 → yirgacheffe-1.7.6}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "yirgacheffe"
-version = "1.7.5"
+version = "1.7.6"
 description = "Abstraction of gdal datasets for doing basic math operations"
 readme = "README.md"
 authors = [{ name = "Michael Dales", email = "mwd24@cam.ac.uk" }]

{yirgacheffe-1.7.5 → yirgacheffe-1.7.6}/tests/test_auto_windowing.py

@@ -201,27 +201,91 @@ def test_constant_layer_result_lhs_multiply() -> None:
 
 def test_vector_layers_add() -> None:
     data1 = np.array([[1, 2], [3, 4]])
-    layer1 = RasterLayer(gdal_dataset_with_data((0.0, 0.0), 1.0, data1))
+    with RasterLayer(gdal_dataset_with_data((0.0, 0.0), 1.1, data1)) as raster_layer:
+        with tempfile.TemporaryDirectory() as tempdir:
+            path = os.path.join(tempdir, "test.gpkg")
+            areas = {
+                (Area(-10.0, 10.0, 0.0, 0.0), 42),
+                (Area(0.0, 0.0, 10, -10), 43)
+            }
+            make_vectors_with_mutlile_ids(areas, path)
+
+            burn_value = 2
+            with VectorLayer.layer_from_file(
+                path,
+                None,
+                raster_layer.map_projection.scale,
+                raster_layer.map_projection.name,
+                burn_value=burn_value
+            ) as vector_layer:
+                layer2_total = vector_layer.sum()
+                assert layer2_total == ((vector_layer.window.xsize * vector_layer.window.ysize) / 2) * burn_value
+
+                calc = raster_layer + vector_layer
+
+                assert calc.area == vector_layer.area
+
+                total = calc.sum()
+                assert total == layer2_total + np.sum(data1)
+
+                with RasterLayer.empty_raster_layer_like(calc) as result:
+                    calc.save(result)
+                    total = result.sum()
+                    assert total == layer2_total + np.sum(data1)
+
+def test_vector_layers_add_unbound_rhs() -> None:
+    data1 = np.array([[1, 2], [3, 4]])
+    with RasterLayer(gdal_dataset_with_data((0.0, 0.0), 1.1, data1)) as raster_layer:
+        with tempfile.TemporaryDirectory() as tempdir:
+            path = os.path.join(tempdir, "test.gpkg")
+            areas = {
+                (Area(-10.0, 10.0, 0.0, 0.0), 42),
+                (Area(0.0, 0.0, 10, -10), 43)
+            }
+            make_vectors_with_mutlile_ids(areas, path)
 
-    with tempfile.TemporaryDirectory() as tempdir:
-        path = os.path.join(tempdir, "test.gpkg")
-        areas = {
-            (Area(-10.0, 10.0, 0.0, 0.0), 42),
-            (Area(0.0, 0.0, 10, -10), 43)
-        }
-        make_vectors_with_mutlile_ids(areas, path)
+            burn_value = 2
+            with VectorLayer.layer_from_file(path, None, None, None, burn_value=burn_value) as vector_layer:
+                calc = raster_layer + vector_layer
 
-        burn_value = 2
-        layer2 = VectorLayer.layer_from_file(path, None, layer1.pixel_scale, layer1.projection, burn_value=burn_value)
-        layer2_total = layer2.sum()
-        assert layer2_total == ((layer2.window.xsize * layer2.window.ysize) / 2) * burn_value
+                layer2_total = ((calc.window.xsize * calc.window.ysize) / 2) * burn_value
 
-        calc = layer1 + layer2
+                assert calc.area != vector_layer.area
 
-        assert calc.area == layer2.area
+                total = calc.sum()
+                assert total == layer2_total + np.sum(data1)
 
-        total = calc.sum()
-        assert total == layer2_total + np.sum(data1)
+                with RasterLayer.empty_raster_layer_like(calc) as result:
+                    calc.save(result)
+                    total = result.sum()
+                    assert total == layer2_total + np.sum(data1)
+
+def test_vector_layers_add_unbound_lhs() -> None:
+    data1 = np.array([[1, 2], [3, 4]])
+    with RasterLayer(gdal_dataset_with_data((0.0, 0.0), 1.1, data1)) as raster_layer:
+        with tempfile.TemporaryDirectory() as tempdir:
+            path = os.path.join(tempdir, "test.gpkg")
+            areas = {
+                (Area(-10.0, 10.0, 0.0, 0.0), 42),
+                (Area(0.0, 0.0, 10, -10), 43)
+            }
+            make_vectors_with_mutlile_ids(areas, path)
+
+            burn_value = 2
+            with VectorLayer.layer_from_file(path, None, None, None, burn_value=burn_value) as vector_layer:
+                calc = vector_layer + raster_layer
+
+                layer2_total = ((calc.window.xsize * calc.window.ysize) / 2) * burn_value
+
+                assert calc.area != vector_layer.area
+
+                total = calc.sum()
+                assert total == layer2_total + np.sum(data1)
+
+                with RasterLayer.empty_raster_layer_like(calc) as result:
+                    calc.save(result)
+                    total = result.sum()
+                    assert total == layer2_total + np.sum(data1)
 
 def test_vector_layers_multiply() -> None:
     data1 = np.array([[1, 2], [3, 4]])

{yirgacheffe-1.7.5 → yirgacheffe-1.7.6}/tests/test_openers.py

@@ -1,5 +1,6 @@
 import os
 import tempfile
+from math import ceil, floor
 from pathlib import Path
 
 import numpy as np
@@ -7,8 +8,9 @@ import pytest
 
 import yirgacheffe as yg
 from yirgacheffe import WGS_84_PROJECTION
-from yirgacheffe.layers import InvalidRasterBand
+from yirgacheffe.layers import InvalidRasterBand, RasterLayer
 from yirgacheffe.window import Area, MapProjection, Window
+from yirgacheffe.operators import DataType
 from tests.helpers import gdal_dataset_of_region, gdal_multiband_dataset_with_data, \
     make_vectors_with_id, make_vectors_with_mutlile_ids
 
@@ -213,3 +215,54 @@ def test_open_two_raster_by_glob(tiled):
             with yg.read_raster(path1) as raster1:
                 with yg.read_raster(path2) as raster2:
                     assert group.sum() == raster1.sum() + raster2.sum()
+
+def test_open_uniform_area_layer() -> None:
+    with tempfile.TemporaryDirectory() as tempdir:
+        path = os.path.join(tempdir, "test.tif")
+        pixel_scale = 0.5
+        area = Area(
+            floor(-180 / pixel_scale) * pixel_scale,
+            ceil(90 / pixel_scale) * pixel_scale,
+            (floor(-180 / pixel_scale) * pixel_scale) + pixel_scale,
+            floor(-90 / pixel_scale) * pixel_scale
+        )
+        dataset = gdal_dataset_of_region(area, pixel_scale, filename=path)
+        assert dataset.RasterXSize == 1
+        assert dataset.RasterYSize == ceil(180 / pixel_scale)
+        dataset.Close()
+
+        with yg.read_narrow_raster(path) as layer:
+            assert layer.map_projection is not None
+            assert layer.map_projection.scale == (pixel_scale, -pixel_scale)
+            assert layer.area == Area(
+                floor(-180 / pixel_scale) * pixel_scale,
+                ceil(90 / pixel_scale) * pixel_scale,
+                ceil(180 / pixel_scale) * pixel_scale,
+                floor(-90 / pixel_scale) * pixel_scale
+            )
+            assert layer.window == Window(
+                0,
+                0,
+                ceil((layer.area.right - layer.area.left) / pixel_scale),
+                ceil((layer.area.top - layer.area.bottom) / pixel_scale)
+            )
+
+def test_incorrect_tiff_for_uniform_area() -> None:
+    with tempfile.TemporaryDirectory() as tempdir:
+        path = Path(tempdir) / "test.tif"
+        area = Area(-10, 10, 10, -10)
+        gdal_dataset_of_region(area, 1.0, filename=path)
+        assert path.exists()
+        with pytest.raises(ValueError):
+            _ = yg.read_narrow_raster(path)
+
+def test_constant() -> None:
+    with yg.constant(42.0) as layer:
+        area = Area(left=-1.0, right=1.0, top=1.0, bottom=-1.0)
+        projection = MapProjection(WGS_84_PROJECTION, 0.1, -0.1)
+        with RasterLayer.empty_raster_layer(area, projection.scale, DataType.Float32) as result:
+            layer.save(result)
+
+            expected = np.full((20, 20), 42.0)
+            actual = result.read_array(0, 0, 20, 20)
+            assert (expected == actual).all()

{yirgacheffe-1.7.5 → yirgacheffe-1.7.6}/tests/test_pickle.py

@@ -30,10 +30,9 @@ def test_pickle_raster_layer() -> None:
 
 def test_pickle_raster_mem_layer_fails() -> None:
     area = Area(-10, 10, 10, -10)
-    layer = RasterLayer(gdal_dataset_of_region(area, 0.02))
-
-    with pytest.raises(ValueError):
-        _ = pickle.dumps(layer)
+    with RasterLayer(gdal_dataset_of_region(area, 0.02)) as layer:
+        with pytest.raises(ValueError):
+            _ = pickle.dumps(layer)
 
 def test_pickle_dyanamic_vector_layer() -> None:
     with tempfile.TemporaryDirectory() as tempdir:

{yirgacheffe-1.7.5 → yirgacheffe-1.7.6}/tests/test_raster.py

@@ -91,6 +91,7 @@ def test_empty_layer_from_raster():
     empty = RasterLayer.empty_raster_layer_like(source)
     assert empty.pixel_scale == source.pixel_scale
     assert empty.projection == source.projection
+    assert empty.map_projection == source.map_projection
     assert empty.window == source.window
     assert empty.datatype == source.datatype
     assert empty.geo_transform == source.geo_transform
@@ -102,6 +103,7 @@ def test_empty_layer_from_raster_with_no_data_value(nodata):
     empty = RasterLayer.empty_raster_layer_like(source, nodata=nodata)
     assert empty.pixel_scale == source.pixel_scale
     assert empty.projection == source.projection
+    assert empty.map_projection == source.map_projection
     assert empty.window == source.window
     assert empty.datatype == source.datatype
     assert empty.geo_transform == source.geo_transform
@@ -113,6 +115,7 @@ def test_empty_layer_from_raster_with_new_smaller_area():
     empty = RasterLayer.empty_raster_layer_like(source, area=smaller_area)
     assert empty.pixel_scale == source.pixel_scale
     assert empty.projection == source.projection
+    assert empty.map_projection == source.map_projection
     assert empty.window == Window(0, 0, 100, 100)
     assert empty.datatype == source.datatype
     assert empty.geo_transform == (-1.0, 0.02, 0.0, 1.0, 0.0, -0.02)
@@ -123,6 +126,7 @@ def test_empty_layer_from_raster_new_datatype():
     empty = RasterLayer.empty_raster_layer_like(source, datatype=gdal.GDT_Float64)
     assert empty.pixel_scale == source.pixel_scale
     assert empty.projection == source.projection
+    assert empty.map_projection == source.map_projection
     assert empty.window == source.window
     assert empty.datatype == DataType.Float64
 
@@ -136,6 +140,7 @@ def test_empty_layer_from_raster_with_window():
     empty = RasterLayer.empty_raster_layer_like(source)
     assert empty.pixel_scale == source.pixel_scale
     assert empty.projection == source.projection
+    assert empty.map_projection == source.map_projection
     assert empty.window.xoff == 0
     assert empty.window.yoff == 0
     assert empty.window.xsize == source.window.xsize

{yirgacheffe-1.7.5 → yirgacheffe-1.7.6}/tests/test_vectors.py

@@ -30,6 +30,7 @@ def test_basic_dynamic_vector_layer() -> None:
             assert layer.geo_transform == (area.left, 1.0, 0.0, area.top, 0.0, -1.0)
             assert layer.window == Window(0, 0, 20, 10)
             assert layer.projection == WGS_84_PROJECTION
+            assert layer.map_projection.name == WGS_84_PROJECTION
 
             # The astype here is to catch escaping MLX types...
             res = layer.read_array(0, 0, 20, 20).astype(int)
@@ -46,6 +47,7 @@ def test_rastered_vector_layer() -> None:
             assert layer.geo_transform == (area.left, 1.0, 0.0, area.top, 0.0, -1.0)
             assert layer.window == Window(0, 0, 20, 10)
             assert layer.projection == WGS_84_PROJECTION
+            assert layer.map_projection.name == WGS_84_PROJECTION
 
 def test_basic_dynamic_vector_layer_no_filter_match() -> None:
     with tempfile.TemporaryDirectory() as tempdir:
@@ -100,6 +102,7 @@ def test_empty_layer_from_vector():
         empty = RasterLayer.empty_raster_layer_like(source)
         assert empty.pixel_scale == source.pixel_scale
         assert empty.projection == source.projection
+        assert empty.map_projection == source.map_projection
         assert empty.window == source.window
         assert empty.area == source.area
 

{yirgacheffe-1.7.5 → yirgacheffe-1.7.6}/yirgacheffe/__init__.py

@@ -12,7 +12,7 @@ except ModuleNotFoundError:
         pyproject_data = tomllib.load(f)
     __version__ = pyproject_data["project"]["version"]
 
-from ._core import read_raster, read_rasters, read_shape, read_shape_like
+from ._core import read_raster, read_rasters, read_shape, read_shape_like, constant, read_narrow_raster
 from .constants import WGS_84_PROJECTION
 
 gdal.UseExceptions()

{yirgacheffe-1.7.5 → yirgacheffe-1.7.6}/yirgacheffe/_core.py

@@ -1,7 +1,9 @@
 from pathlib import Path
 from typing import Optional, Sequence, Tuple, Union
 
+from .layers.area import UniformAreaLayer
 from .layers.base import YirgacheffeLayer
+from .layers.constant import ConstantLayer
 from .layers.group import GroupLayer, TiledGroupLayer
 from .layers.rasters import RasterLayer
 from .layers.vectors import VectorLayer
@@ -31,6 +33,33 @@ def read_raster(
     """
     return RasterLayer.layer_from_file(filename, band, ignore_nodata)
 
+def read_narrow_raster(
+    filename: Union[Path,str],
+    band: int = 1,
+    ignore_nodata: bool = False,
+) -> RasterLayer:
+    """Open a 1 pixel wide raster file as a global raster.
+
+    This exists for the special use case where an area per pixel raster would have the same value per horizontal row
+    (e.g., a WGS84 map projection). For that case you can use this to load a raster that is 1 pixel wide and have
+    it automatically expanded to act like a global raster in calculations.
+
+    Parameters
+    ----------
+    filename : Path
+        Path of raster file to open.
+    band : int, default=1
+        For multi-band rasters, which band to use (defaults to first if not specified)
+    ignore_nodata : bool, default=False
+        If the GeoTIFF has a NODATA value, don't subsitute that value for NaN
+
+    Returns
+    -------
+    RasterLayer
+        Returns an layer representing the raster data.
+    """
+    return UniformAreaLayer.layer_from_file(filename, band, ignore_nodata)
+
 def read_rasters(
     filenames : Sequence[Union[Path,str]],
     tiled: bool=False
@@ -132,3 +161,23 @@ def read_shape_like(
         datatype,
         burn_value,
     )
+
+def constant(value: Union[int,float]) -> ConstantLayer:
+    """Generate a layer that has the same value in all pixels regardless of scale, projection, and area.
+
+    Generally this should not be necessary unless you must have the constant as the first term in an
+    expression, as Yirgacheffe will automatically convert numbers into constant layers. However if the
+    constant is the first term in the expression it must be wrapped by this call otherwise Python will
+    not know that it should be part of the Yirgacheffe expression.
+
+    Parameters
+    ----------
+    value : int or float
+        The value to be in each pixel of the expression term.
+
+    Returns
+    -------
+    ConstantLayer
+        Returns a constant layer of the provided value.
+    """
+    return ConstantLayer(value)

{yirgacheffe-1.7.5 → yirgacheffe-1.7.6}/yirgacheffe/layers/rasters.py

@@ -97,8 +97,6 @@ class RasterLayer(YirgacheffeLayer):
         threads: Optional[int]=None,
         bands: int=1
     ) -> RasterLayer:
-        width = layer.window.xsize
-        height = layer.window.ysize
         if area is None:
             area = layer.area
         assert area is not None
@@ -117,6 +115,12 @@ class RasterLayer(YirgacheffeLayer):
             area.left, projection.xstep, 0.0, area.top, 0.0, projection.ystep
         )
 
+        if area is None:
+            og_width = layer.window.xsize
+            og_height = layer.window.ysize
+            assert (og_width == width) and (og_height == height), \
+                f"original size ({og_width}, {og_height}) != estimated ({width}, {height})"
+
         if datatype is None:
             datatype_arg = layer.datatype
         elif isinstance(datatype, int):

{yirgacheffe-1.7.5 → yirgacheffe-1.7.6}/yirgacheffe/layers/vectors.py

@@ -4,8 +4,10 @@ from pathlib import Path
 from typing import Any, Optional, Tuple, Union
 from typing_extensions import NotRequired
 
+import deprecation
 from osgeo import gdal, ogr
 
+from .. import __version__
 from ..operators import DataType
 from ..window import Area, MapProjection, PixelScale
 from .base import YirgacheffeLayer
@@ -60,6 +62,12 @@ class RasteredVectorLayer(RasterLayer):
     VectorLayer."""
 
     @classmethod
+    @deprecation.deprecated(
+        deprecated_in="1.7",
+        removed_in="2.0",
+        current_version=__version__,
+        details="Use `VectorLayer` instead."
+    )
     def layer_from_file( # type: ignore[override] # pylint: disable=W0221
         cls,
         filename: Union[Path,str],

{yirgacheffe-1.7.5 → yirgacheffe-1.7.6}/yirgacheffe/operators.py

@@ -387,50 +387,9 @@ class LayerOperation(LayerMathMixin):
 
     @property
     def area(self) -> Area:
-        # The type().__name__ here is to avoid a circular import dependancy
-        lhs_area = self.lhs.area
-        try:
-            rhs_area = self.rhs.area
-        except AttributeError:
-            rhs_area = None
-        try:
-            other_area = self.other.area
-        except AttributeError:
-            other_area = None
-
-        all_areas = [x for x in [lhs_area, rhs_area, other_area] if (x is not None) and (not x.is_world)]
-
-        match self.window_op:
-            case WindowOperation.NONE:
-                return all_areas[0]
-            case WindowOperation.LEFT:
-                return lhs_area
-            case WindowOperation.RIGHT:
-                assert rhs_area is not None
-                return rhs_area
-            case WindowOperation.INTERSECTION:
-                intersection = Area(
-                    left=max(x.left for x in all_areas),
-                    top=min(x.top for x in all_areas),
-                    right=min(x.right for x in all_areas),
-                    bottom=max(x.bottom for x in all_areas)
-                )
-                if (intersection.left >= intersection.right) or (intersection.bottom >= intersection.top):
-                    raise ValueError('No intersection possible')
-                return intersection
-            case WindowOperation.UNION:
-                return Area(
-                    left=min(x.left for x in all_areas),
-                    top=max(x.top for x in all_areas),
-                    right=max(x.right for x in all_areas),
-                    bottom=min(x.bottom for x in all_areas)
-                )
-            case _:
-                assert False, "Should not be reached"
+        return self._get_operation_area(self.map_projection)
 
     def _get_operation_area(self, projection: Optional[MapProjection]) -> Area:
-
-        # The type().__name__ here is to avoid a circular import dependancy
         lhs_area = self.lhs._get_operation_area(projection)
         try:
             rhs_area = self.rhs._get_operation_area(projection)
@@ -462,12 +421,13 @@ class LayerOperation(LayerMathMixin):
                     raise ValueError('No intersection possible')
                 return intersection
             case WindowOperation.UNION:
-                return Area(
+                union = Area(
                     left=min(x.left for x in all_areas),
                     top=max(x.top for x in all_areas),
                     right=max(x.right for x in all_areas),
                     bottom=min(x.bottom for x in all_areas)
                 )
+                return union
             case _:
                 assert False, "Should not be reached"
 

{yirgacheffe-1.7.5 → yirgacheffe-1.7.6/yirgacheffe.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: yirgacheffe
-Version: 1.7.5
+Version: 1.7.6
 Summary: Abstraction of gdal datasets for doing basic math operations
 Author-email: Michael Dales <mwd24@cam.ac.uk>
 License-Expression: ISC
@@ -262,17 +262,33 @@ Notes:
 * You can have missing tiles, and these will be filled in with zeros.
 * You can have tiles that overlap, so long as they still conform to the rule that all tiles are the same size and on a grid.
 
-### ConstantLayer
+### Constants
 
-This is there to simplify code when you have some optional layers. Rather than littering your code with checks, you can just use a constant layer, which can be included in calculations and will just return an fixed value as if it wasn't there. Useful with 0.0 or 1.0 for sum or multiplication null layers.
+At times it is useful to have a fixed constant in an expression. Typically, similar to numpy, if an expression involving layers has a constant in, Yirgacheffe will apply that to all pixels in the equation without need for further elaboration:
+
+```python
+with yg.read_raster("some_data.tif") as layer:
+    doubled_layer = layer * 2.0
+    ...
+```
+
+This can be useful in tasks where you have an optional layer in your code. For example, here the code optionally loads an area-per-pixel layer, which if not present can just be substituted with a 1.0:
 
 ```python
 try:
-    area_layer = RasterLayer.layer_from_file('myarea.tiff')
+    area_layer = yg.read_raster('myarea.tiff')
 except FileDoesNotExist:
-    area_layer = ConstantLayer(0.0)
+    area_layer = 1.0
 ```
 
+However, as with numpy, Python can not make the correct inference if the constant value is the first term in the equation. In that case you need to explicitly wrap the value with `constant` to help Python understand what is happening:
+
+```python
+with yg.read_raster("some_data.tif") as layer:
+    result = yg.constant(1.0) / layer
+```
+
+
 ### H3CellLayer
 
 If you have H3 installed, you can generate a mask layer based on an H3 cell identifier, where pixels inside the cell will have a value of 1, and those outside will have a value of 0.