Metadata-Version: 2.1
Name: nismod-snail
Version: 0.5.4
Summary: The spatial networks impact assessment library
Author: Thibault Lestang, Raghav Pant, Lena Fuldauer
Author-Email: Tom Russell <tomalrussell@gmail.com>
Maintainer-Email: Tom Russell <tomalrussell@gmail.com>
License: MIT License
        
        Copyright (c) 2020 Tom Russell and snail contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Utilities
Project-URL: Homepage, https://github.com/nismod/snail
Project-URL: Documentation, https://nismod.github.io/snail/
Project-URL: Repository, https://github.com/nismod/snail.git
Requires-Python: >=3.8
Requires-Dist: geopandas
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: openpyxl
Requires-Dist: pandera
Requires-Dist: pyarrow
Requires-Dist: pyogrio
Requires-Dist: igraph
Requires-Dist: rasterio
Requires-Dist: shapely
Requires-Dist: scipy
Requires-Dist: affine; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: hilbertcurve; extra == "dev"
Requires-Dist: nbstripout; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: sphinx_gallery; extra == "docs"
Requires-Dist: numpydoc; extra == "docs"
Requires-Dist: contextily; extra == "tutorials"
Requires-Dist: irv_autopkg_client; extra == "tutorials"
Requires-Dist: jupyter; extra == "tutorials"
Requires-Dist: networkx; extra == "tutorials"
Requires-Dist: seaborn; extra == "tutorials"
Requires-Dist: snkit; extra == "tutorials"
Requires-Dist: tqdm; extra == "tutorials"
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: tutorials
Description-Content-Type: text/markdown

<p align="center">
<a href="https://github.com/nismod/snail/tree/main/docs/source/tutorials">Tutorials</a> |
<a href="https://github.com/nismod/snail/issues">Issues</a>
</p>

<p align="center">
<img src="./images/snail.svg" alt="snail" />
</p>

[![PyPI version](https://img.shields.io/pypi/v/nismod-snail.svg)](https://pypi.org/project/nismod-snail/)
[![Build](https://github.com/nismod/snail/actions/workflows/build.yml/badge.svg)](https://github.com/nismod/snail/actions/workflows/build.yml)
[![License](https://img.shields.io/pypi/l/nismod-snail.svg)](https://opensource.org/licenses/MIT)

# 🤔 What is this?

This is a Python package to help with analysis of the potential impacts of
climate hazards and other perils on infrastructure networks.

## Installation

Install using pip:

    pip install nismod-snail

This should bring all dependencies with it. If any of these cause difficulties,
try using a [conda](https://docs.conda.io/en/latest/miniconda.html) environment:

    conda env create -n snail_env \
        python=3.11 geopandas shapely rasterio python-igraph
    conda activate snail_env
    pip install nismod-snail

If all worked okay, you should be able to run python and import snail:

    $ python
    >>> import snail
    >>> help(snail)
    Help on package snail:

    NAME
        snail - snail - the spatial networks impact assessment library

## Using the `snail` command

Once installed, you can use `snail` directly from the command line.

Split features on a grid defined by its transform, width and height:

```bash
snail split \
    --features input.shp \
    --transform 1 0 -180 0 -1 90 \
    --width 360 \
    --height 180 \
    --output split.gpkg
```

Split features on a grid defined by a GeoTIFF, optionally adding the values from each raster band to each split feature as a new attribute:

```bash
snail split \
    --features lines.geojson \
    --raster gridded_data.tif \
    --attribute \
    --output split_lines_with_raster_values.geojson
```

Split multiple vector feature files along the grids defined by multiple raster files, attributing all raster values:

```bash
snail process -fs features.csv -rs rasters.csv
```

Where at a minimum, each CSV has a column `path` with the path to each file.

### Transform

A note on `transform` - these six numbers define the transform from `i,j` cell index (column/row) coordinates in the rectangular grid to `x,y` geographic coordinates, in the coordinate reference system of the input and output files. They effectively form the first two rows of a 3x3 matrix:

```
| x |   | a  b  c | | i |
| y | = | d  e  f | | j |
| 1 |   | 0  0  1 | | 1 |
```

In cases without shear or rotation, `a` and `e` define scaling or grid cell size, while `c` and `f` define the offset or grid upper-left corner:

```
| x_scale 0       x_offset |
| 0       y_scale y_offset |
| 0       0       1        |
```

See [`rasterio/affine`](https://github.com/rasterio/affine#usage) and [GDAL Raster Data Model](https://gdal.org/user/raster_data_model.html#affine-geotransform) for more documentation.

## Development

Clone this repository using [GitHub Desktop](https://desktop.github.com/) or on
the command line:

    git clone git@github.com:nismod/snail.git

Change directory into the root of the project:

    cd snail

To create and activate a conda environment with snail's dependencies installed:

    conda env create -f environment.yml
    conda activate snail-dev

Run this to install the source code as a package:

    pip install .

If you're working on snail itself, install it as "editable" along with test and
development packages:

    pip install -e .[dev]

Run tests using [pytest](https://docs.pytest.org/en/latest/) and
[pytest-cov](https://pytest-cov.readthedocs.io) to check coverage:

    pytest --cov=snail --cov-report=term-missing

Run a formatter ([black](https://github.com/psf/black)) to fix code
formatting:

    black src/snail

When working on the tutorial notebooks, it is recommended to install and
configure [nbstripout](https://github.com/kynan/nbstripout) so data and outputs
are not committed in the notebook files:

    nbstripout --install

### C++ library

The C++ library in `extension/src` contains the core routines to find intersections of
lines with raster grids.

Before working on the C++ library, fetch source code for Catch2 unit testing
library (this is included as a git submodule):

    git submodule update --init --recursive

Build the library and run tests:

    cmake -Bbuild ./extension
    cmake --build build/
    ./build/run_tests

Run code style auto-formatting:

    clang-format -i extension/src/*.{cpp,hpp}

Run lints and checks:

    clang-tidy --checks 'cppcoreguidelines-*' extension/src/*.{cpp,hpp}

This may need some includes for `pybind11` - which will vary depending on your
python installation. For example, with python via miniconda:

    clang-tidy --checks 'cppcoreguidelines-*' extension/src/* -- \
        -I/home/username/miniconda3/include/python3.11/ \
        -I./pybind11/include/

Or with C++ headers installed on a Linux machine:

    clang-tidy --checks 'cppcoreguidelines-*' extension/src/* -- \
        -std=c++14  \
        -I/usr/include/x86_64-linux-gnu/c++/11 \
        -I/usr/include/c++/11 \
        -I{$PWD}/extension/extern/pybind11/include \
        -I/usr/include/python3.10

### Integration of C++ and Python using pybind11

The `snail.core.intersections` module is built using `pybind11` with
`scikit-build-core` (see [docs](https://scikit-build-core.readthedocs.io/en/latest/))

- `extension/src/intersections.cpp` defines the module interface using the
  `PYBIND11_MODULE` macro
- `pyproject.toml` defines the build requirements for snail, which includes
  pybind11 and scikit-build-core

## Acknowledgments

> MIT License
>
> Copyright (c) 2020-23 Tom Russell and all [snail contributors](https://github.com/nismod/snail/graphs/contributors)

This library is developed by researchers in the [Oxford Programme for Sustainable
Infrastructure Systems](https://opsis.eci.ox.ac.uk/) at the University of Oxford,
funded by multiple research projects.

This research received funding from the FCDO Climate Compatible Growth Programme.
The views expressed here do not necessarily reflect the UK government's official
policies.
