Metadata-Version: 2.4
Name: fastnsa
Version: 0.3.1
Summary: High-performance network-constrained spatial point pattern analysis in Python
Keywords: GIS,spatial,network,point-pattern,K-function
Author: FastNSA Project
License-Expression: LGPL-2.1-only
License-File: python/LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Mathematics
Project-URL: Homepage, https://github.com/fastnsa/FastNSA
Project-URL: Repository, https://github.com/fastnsa/FastNSA
Project-URL: Issues, https://github.com/fastnsa/FastNSA/issues
Project-URL: Documentation, https://github.com/fastnsa/FastNSA/tree/main/python/docs
Requires-Python: >=3.9
Requires-Dist: numpy>=1.23.5
Provides-Extra: dataframe
Requires-Dist: pandas; extra == "dataframe"
Provides-Extra: xarray
Requires-Dist: xarray; extra == "xarray"
Provides-Extra: geo
Requires-Dist: pandas; extra == "geo"
Requires-Dist: geopandas; extra == "geo"
Requires-Dist: shapely; extra == "geo"
Provides-Extra: osm
Requires-Dist: pandas; extra == "osm"
Requires-Dist: geopandas; extra == "osm"
Requires-Dist: shapely; extra == "osm"
Requires-Dist: networkx; extra == "osm"
Requires-Dist: osmnx; extra == "osm"
Provides-Extra: viz
Requires-Dist: matplotlib; extra == "viz"
Provides-Extra: all
Requires-Dist: pandas; extra == "all"
Requires-Dist: geopandas; extra == "all"
Requires-Dist: shapely; extra == "all"
Requires-Dist: networkx; extra == "all"
Requires-Dist: osmnx; extra == "all"
Requires-Dist: matplotlib; extra == "all"
Requires-Dist: xarray; extra == "all"
Description-Content-Type: text/markdown

# FastNSA Python

FastNSA is a native-accelerated Python toolkit for network-constrained spatial
point analysis. It provides point-to-network mapping, network kernel density
estimation (NKDE), network K-functions, and spatiotemporal network K-functions.

The package has two integration levels:

- A lightweight array API based on NumPy and the native FastNSA library.
- A geospatial API for GeoPandas, Shapely, NetworkX, and OSMnx workflows.

## Installation

FastNSA 0.3.1 requires Python 3.9 or newer and NumPy 1.23.5 or newer.
Install the package with:

~~~bash
python -m pip install fastnsa
~~~

See the [installation guide](docs/installation.md) for source builds and
version requirements, or the [release notes](docs/releases/0.3.1.md) for changes
in this version.

Published binary wheels determine the supported operating systems, CPU
architectures, and Python versions for each release. If no compatible wheel is
available, pip may attempt a source build, which requires CMake and a C++17
compiler.

Install only the optional integrations you need:

~~~bash
python -m pip install "fastnsa[dataframe]"  # pandas exports
python -m pip install "fastnsa[xarray]"     # ST result DataArray exports
python -m pip install "fastnsa[geo]"        # GeoPandas and Shapely workflows
python -m pip install "fastnsa[osm]"        # NetworkX and OSMnx workflows
python -m pip install "fastnsa[viz]"        # Matplotlib visualizations
python -m pip install "fastnsa[all]"        # all optional integrations
~~~

## Minimal Example

The bundled line dataset is useful for installation checks and examples. It
does not require GeoPandas, NetworkX, or OSMnx.

~~~python
import fastnsa as nsa

network = nsa.make_line_network(length=1000.0)
events = nsa.make_line_events(network, offsets=[100.0, 350.0, 700.0, 900.0])

result = nsa.network_k_function(
    network=network,
    points=events,
    r_values=[50.0, 100.0, 250.0],
    method=nsa.KFunctionMethod.STARS,
    simulations=5,
    random_state=2026,
)

print(result.to_records())
result.save_npz("network_k_result.npz")
restored = nsa.load_result("network_k_result.npz")

events.close()
network.close()
~~~

Native resources are context managers, so larger applications can use a
deterministic lifecycle:

~~~python
with nsa.make_line_network() as network:
    with nsa.make_line_events(network) as events:
        result = nsa.network_k_function(
            network=network,
            points=events,
            r_max=500.0,
            r_step=50.0,
        )
~~~

## Geospatial Workflow

With the osm extra installed, a network can be downloaded through OSMnx and
event files can be loaded through GeoPandas:

~~~python
import fastnsa as nsa

network = nsa.Network.from_osm(place="Central Park, New York", network_type="drive")
points = nsa.load_points("events.gpkg", layer="events", time_col="event_time")
events = nsa.PointEvents(points, target_network=network, time_col="event_time")

k_result = nsa.network_k_function(
    network=network,
    points=events,
    r_min=0.0,
    r_max=2000.0,
    r_step=50.0,
    method=nsa.KFunctionMethod.STARS,
    simulations=99,
    envelope="global",
)
~~~

Use a projected coordinate reference system whose map units are metres for
distance-based analyses. FastNSA does not interpret degree coordinates as
geodesic distances.

## Main Features

- Point mapping with R-tree, exact comparison, and approximate comparison.
- NKDE methods including ADA and LION with optional event weights.
- Network K-function methods SPS, NS, and STARS.
- Spatiotemporal methods RQS, SPS, EAR, MTS, and EARTH.
- Pointwise or global Monte Carlo envelopes, reproducible seeds, and p-values.
- CSV, pandas, NPZ, and optional xarray result exports.
- Progress callbacks and cooperative cancellation for host applications.
- Direct NumPy inputs for array-based analysis without geospatial dependencies.

## Documentation

- [Documentation index](docs/index.md)
- [Installation and deployment](docs/installation.md)
- [Quick start](docs/quickstart.md)
- [Data model and preprocessing](docs/data-model.md)
- [Analysis methods](docs/analyses.md)
- [Results and persistence](docs/results.md)
- [API reference](docs/api-reference.md)
- [Algorithm references](docs/references.md)
- [Troubleshooting](docs/troubleshooting.md)
- [中文使用指南](docs/README_ZH.md)

## License

FastNSA is licensed under GNU LGPL v2.1 only. Applications may dynamically
link to the library under the LGPL terms. Modifications to the FastNSA library
itself must remain available under the applicable LGPL requirements. See the
packaged LICENSE file for the complete license text.
