Core

To get started with yirgacheffe you can import data using the following core methods.

`read_raster(filename, band=1, ignore_nodata=False)`

Open a raster file (e.g., GeoTIFF).

Parameters:

Name	Type	Description	Default
`filename`	`Path \| str`	Path of raster file to open.	required
`band`	`int`	For multi-band rasters, which band to use (defaults to first if not specified).	`1`
`ignore_nodata`	`bool`	If the GeoTIFF has a NODATA value, don't substitute that value for NaN.	`False`

Returns:

Type	Description
`YirgacheffeLayer`	An layer representing the raster data.

Examples:

>>> import yirgacheffe as yg
>>> with yg.read_raster('test.tif') as layer:
...     total = layer.sum()

`read_raster_like(filename, like, method, band=1, ignore_nodata=False)`

Open a raster file but reproject it to match another layer.

This method can be used to reproject a raster in one map projection to match another open layer.

The reprojection will be only done when the data is actually used in a calculation, so unused data will not be reprojected.

Parameters:

Name	Type	Description	Default
`filename`	`Path \| str`	Path of raster file to open.	required
`like`	`YirgacheffeLayer`	Another layer that has a projection and pixel scale set. This layer will use the same projection and pixel scale as that one.	required
`method`	`ResamplingMethod`	The resampling method that will be used during the reprojection.	required
`band`	`int`	For multi-band rasters, which band to use (defaults to first if not specified).	`1`
`ignore_nodata`	`bool`	If the GeoTIFF has a NODATA value, don't substitute that value for NaN.	`False`

Returns:

Type	Description
`YirgacheffeLayer`	An layer representing the raster data in the new projection.

Note

For parallel processing, use Python's multiprocessing module. This layer is safe when used with multiprocessing, but calls to read_array on an object are not thread safe.

Examples:

>>> import yirgacheffe as yg
>>> with (
...     yg.read_raster('map_in_esri_54009.tif') as layer1,
...     yg.read_raster_like('map_in_wgs84.tif', layer1, yg.ResamplingMethod.Nearest) as layer2
... ):
...     res = layer1 * layer2
...     res.to_geotiff('result_in_esri_54009.tif')

`read_shape(filename, projection=None, where_filter=None, datatype=None, burn_value=1)`

Open a polygon file (e.g., GeoJSON, GPKG, or ESRI Shape File).

Parameters:

Name	Type	Description	Default
`filename`	`Path \| str`	Path of vector file to open.	required
`projection`	`MapProjection \| tuple[str, tuple[float, float]] \| None`	The map projection to use.	`None`
`where_filter`	`str \| None`	For use with files with many entries (e.g., GPKG), applies this filter to the data.	`None`
`datatype`	`dtype \| None`	Specify the data type of the raster data generated.	`None`
`burn_value`	`int \| float \| str`	The value of each pixel in the polygon.	`1`

Returns:

Type	Description
`YirgacheffeLayer`	An layer representing the vector data.

Examples:

>>> import yirgacheffe as yg
>>> with yg.read_shape('range.gpkg') as layer:
...    ...

`read_shape_like(filename, like, where_filter=None, datatype=None, burn_value=1)`

Open a polygon file (e.g., GeoJSON, GPKG, or ESRI Shape File).

Parameters:

Name	Type	Description	Default
`filename`	`Path \| str`	Path of vector file to open.	required
`like`	`YirgacheffeLayer`	Another layer that has a projection and pixel scale set. This layer will use the same projection and pixel scale as that one.	required
`where_filter`	`str \| None`	For use with files with many entries (e.g., GPKG), applies this filter to the data.	`None`
`datatype`	`dtype \| None`	Specify the data type of the raster data generated.	`None`
`burn_value`	`int \| float \| str`	The value of each pixel in the polygon.	`1`

Returns:

Type	Description
`YirgacheffeLayer`	An layer representing the vector data.

`read_rasters(filenames, tiled=False)`

Open a set of raster files (e.g., GeoTIFFs) as a single layer.

Parameters:

Name	Type	Description	Default
`filenames`	`Sequence[Path \| str]`	List of paths of raster files to open.	required
`tiled`	`bool`	If you know that the rasters for a regular tileset, then setting this flag allows Yirgacheffe to perform certain optimisations that significantly improve performance for this use case.	`False`

Returns:

Type	Description
`YirgacheffeLayer`	An layer representing the raster data.

Examples:

>>> import yirgacheffe as yg
>>> with yg.read_rasters(['tile_N10_E10.tif', 'tile_N20_E10.tif']) as all_tiles:
...    ...

`constant(value)`

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:

Name	Type	Description	Default
`value`	`int \| float`	The value to be in each pixel of the expression term.	required

Returns:

Type	Description
`YirgacheffeLayer`	A constant layer of the provided value.

`from_array(values, origin, projection)`

Creates an in-memory layer from a numerical array.

Parameters:

Name	Type	Description	Default
`values`	`ndarray`	a 2D array of data values, with Y on the first dimension, X on the second dimension.	required
`origin`	`tuple[float, float]`	the position of the top left pixel in the geospatial space	required
`projection`	`MapProjection \| tuple[str, tuple[float, float]]`	the map projection and pixel scale to use.	required

Returns:

Type	Description
`YirgacheffeLayer`	A geospatial layer that uses the provided data for its values.