pyOpenSci and JOSS submission

.github/workflows/draft-pdf.yml

@@ -0,0 +1,35 @@
+name: Draft PDF
+on:
+  push:
+    paths:
+    - 'docs/paper/**'
+    - .github/workflows/draft-pdf.yml
+
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Paper Draft
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          # This should be the path to the paper within your repo.
+          paper-path: docs/paper/paper.md
+      - name: Upload
+        uses: actions/upload-artifact@v4
+        with:
+          name: paper
+          # This is the output path where Pandoc will write the compiled
+          # PDF. Note, this should be the same directory as the input
+          # paper.md
+          path: docs/paper/paper.pdf
+      - name: Commit PDF to repository
+        uses: EndBug/add-and-commit@v9
+        with:
+          message: '(auto) Paper PDF Draft'
+          # This should be the path to the paper within your repo.
+          add: 'docs/paper/paper.pdf' # 'paper/*.pdf' to commit all PDFs in the paper directory

.pre-commit-config.yaml

@@ -66,7 +66,7 @@ repos:
     rev: 1.0.0
     hooks:
       - id: mdformat
-        exclude: '.github/\w+.md'
+        exclude: '.github/\w+.md|docs/paper/paper.md'
   - repo: https://github.com/keewis/blackdoc
     rev: v0.4.6
     hooks:

.zenodo.json

@@ -1,5 +1,5 @@
 {
-  "title": "LSAPy: Land Suitability Analysis (LSA) in Python",
+  "title": "LSAPy: Land Suitability Analysis in Python",
   "creators": [
     {
       "name": "Hamon, Baptiste",

docs/paper/paper.bib

@@ -0,0 +1,234 @@
+@article{asaad2022,
+  title = {{ALUES}: R package for Agricultural Land Use Evaluation System},
+  volume = {7},
+  issn = {2475-9066},
+  url = {https://joss.theoj.org/papers/10.21105/joss.04228},
+  doi = {10.21105/joss.04228},
+  shorttitle = {{ALUES}},
+  pages = {4228},
+  number = {73},
+  journaltitle = {Journal of Open Source Software},
+  author = {Asaad, Al-Ahmadgaid B. and Salvacion, Arnold R. and Yen, Bui Tan},
+  urldate = {2025-08-23},
+  date = {2022-05-12},
+  langid = {english}
+}
+
+
+@book{carr2007,
+  title = {Smart Land-use Analysis: The {LUCIS} Model Land-use Conflict Identification
+    Strategy},
+  isbn = {978-1-58948-174-9},
+  shorttitle = {Smart Land-use Analysis},
+  pagetotal = {292},
+  publisher = {{ESRI}, Inc.},
+  author = {Carr, Margaret H. and Zwick, Paul Dean},
+  date = {2007},
+  langid = {english},
+  note = {Google-Books-{ID}: {GOQYfZldMboC}},
+  keywords = {Business \& Economics / Development / Economic Development, Political Science
+    / Public Policy / Regional Planning}
+}
+
+
+@article{chen2022,
+  title = {{PyLUSAT}: An open-source Python toolkit for {GIS}-based land use suitability
+    analysis},
+  volume = {151},
+  issn = {1364-8152},
+  url = {https://www.sciencedirect.com/science/article/pii/S1364815222000688},
+  doi = {10.1016/j.envsoft.2022.105362},
+  shorttitle = {{PyLUSAT}},
+  pages = {105362},
+  journaltitle = {Environmental Modelling \& Software},
+  shortjournal = {Environmental Modelling \& Software},
+  author = {Chen, Changjie and Judge, Jasmeet and Hulse, David},
+  urldate = {2025-08-23},
+  date = {2022-05-01},
+  keywords = {{GIS}, Geospatial analysis, Land use planning, Open-source software, Python,
+    Suitability modeling}
+}
+
+
+@article{delarosa1992,
+  title = {{MicroLEIS}: A microcomputer-based Mediterranean land evaluation information
+    system},
+  volume = {8},
+  issn = {0266-0032, 1475-2743},
+  url = {    https://bsssjournals.onlinelibrary.wiley.com/doi/10.1111/j.1475-2743.1992.tb00900.x},
+  doi = {10.1111/j.1475-2743.1992.tb00900.x},
+  shorttitle = {{MicroLEIS}},
+  pages = {89--96},
+  number = {2},
+  journaltitle = {Soil Use and Management},
+  shortjournal = {Soil Use and Management},
+  author = {De La Rosa, D. and Moreno, J. A. and Garcia, L. V. and Almorza, J.},
+  urldate = {2025-08-24},
+  date = {1992-06},
+  langid = {english}
+}
+
+
+@article{delarosa2004,
+  title = {A land evaluation decision support system ({MicroLEIS} {DSS}) for agricultural
+    soil protection},
+  volume = {19},
+  rights = {https://www.elsevier.com/tdm/userlicense/1.0/},
+  issn = {13648152},
+  url = {https://linkinghub.elsevier.com/retrieve/pii/S1364815203002184},
+  doi = {10.1016/j.envsoft.2003.10.006},
+  pages = {929--942},
+  number = {10},
+  journaltitle = {Environmental Modelling \& Software},
+  shortjournal = {Environmental Modelling \& Software},
+  author = {De La Rosa, D and Mayol, F and Diaz-Pereira, E and Fernandez, M and De La Rosa,
+    D},
+  urldate = {2025-08-24},
+  date = {2004-10},
+  langid = {english}
+}
+
+
+@article{elsheikh2013,
+  title = {Agriculture Land Suitability Evaluator ({ALSE}): A decision and planning support
+    tool for tropical and subtropical crops},
+  volume = {93},
+  issn = {0168-1699},
+  url = {https://www.sciencedirect.com/science/article/pii/S016816991300032X},
+  doi = {10.1016/j.compag.2013.02.003},
+  shorttitle = {Agriculture Land Suitability Evaluator ({ALSE})},
+  pages = {98--110},
+  journaltitle = {Computers and Electronics in Agriculture},
+  shortjournal = {Computers and Electronics in Agriculture},
+  author = {Elsheikh, Ranya and Mohamed Shariff, Abdul Rashid B. and Amiri, Fazel and
+    Ahmad, Noordin B. and Balasundram, Siva Kumar and Soom, Mohd Amin Mohd},
+  urldate = {2025-08-23},
+  date = {2013-04-01},
+  keywords = {{GIS}, Land use planning, Biophysical modeling, Expert system, Land
+    evaluation, Multi-criteria analysis}
+}
+
+
+@inproceedings{hamon2025a,
+  title = {Bridging the Gaps in the Future Agroclimatic Suitability of Crops in New Zealand},
+  doi = {10.5194/egusphere-egu25-1157},
+  eventtitle = {{EGU} General Assembly 2025, Vienna, Austria, 27 Apr-2 May 2025,
+    {EGU}25-1157},
+  author = {Hamon, Baptiste and Quénol, Hervé and Vannier, Clémence and Cochrane, Thomas},
+  urldate = {2025-03-16},
+  date = {2025},
+  langid = {english}
+}
+
+
+@unpublished{hamon2025c,
+  title = {Regional Impacts of Climate Change on New Zealand's Agriculture: Land
+    Suitability Analysis of Key Crops},
+  journaltitle = {[Manuscript submitted for publication]},
+  author = {Hamon, Baptiste and Quénol, Hervé and Vannier, Clémence and Cochrane, Thomas A.},
+  date = {2025}
+}
+
+
+@misc{hamon2025d,
+  title = {New Zealand Gridded Land Information Dataset ({NZGLID})},
+  rights = {Creative Commons Attribution 4.0 International},
+  url = {https://zenodo.org/doi/10.5281/zenodo.16249350},
+  doi = {10.5281/ZENODO.16249350},
+  version = {v1.1},
+  publisher = {Zenodo},
+  author = {Hamon, Baptiste},
+  urldate = {2025-08-27},
+  date = {2025-08-12},
+  langid = {english},
+  keywords = {{GIS}, Land Use/Land Cover, New Zealand, Soil Parameters, Terrain}
+}
+
+
+@article{hoyer2017,
+  title = {xarray: N-D labeled Arrays and Datasets in Python},
+  volume = {5},
+  issn = {2049-9647},
+  url = {https://openresearchsoftware.metajnl.com/articles/10.5334/jors.148},
+  doi = {10.5334/jors.148},
+  shorttitle = {xarray},
+  number = {1},
+  journaltitle = {Journal of Open Research Software},
+  author = {Hoyer, Stephan and Hamman, Joe},
+  urldate = {2025-08-25},
+  date = {2017-04-05},
+  langid = {english}
+}
+
+
+@article{johnson1991,
+  title = {Development of a simulation based land evaluation system using crop modelling,
+    expert systems and risk analysis},
+  volume = {7},
+  issn = {0266-0032, 1475-2743},
+  url = {    https://bsssjournals.onlinelibrary.wiley.com/doi/10.1111/j.1475-2743.1991.tb00881.x},
+  doi = {10.1111/j.1475-2743.1991.tb00881.x},
+  pages = {239--246},
+  number = {4},
+  journaltitle = {Soil Use and Management},
+  shortjournal = {Soil Use and Management},
+  author = {Johnson, A. K. L. and Cramb, R. A.},
+  urldate = {2025-08-24},
+  date = {1991-12},
+  langid = {english}
+}
+
+
+@article{kalogirou2002,
+  title = {Expert systems and {GIS}: an application of land suitability evaluation},
+  volume = {26},
+  rights = {https://www.elsevier.com/tdm/userlicense/1.0/},
+  issn = {01989715},
+  url = {https://linkinghub.elsevier.com/retrieve/pii/S019897150100031X},
+  doi = {10.1016/S0198-9715(01)00031-X},
+  shorttitle = {Expert systems and {GIS}},
+  pages = {89--112},
+  number = {2},
+  journaltitle = {Computers, Environment and Urban Systems},
+  shortjournal = {Computers, Environment and Urban Systems},
+  author = {Kalogirou, S},
+  urldate = {2025-08-24},
+  date = {2002-03},
+  langid = {english}
+}
+
+
+@article{malczewski2004,
+  title = {{GIS}-based land-use suitability analysis: a critical overview},
+  volume = {62},
+  issn = {03059006},
+  url = {https://linkinghub.elsevier.com/retrieve/pii/S0305900603000801},
+  doi = {10.1016/j.progress.2003.09.002},
+  shorttitle = {{GIS}-based land-use suitability analysis},
+  pages = {3--65},
+  number = {1},
+  journaltitle = {Progress in Planning},
+  shortjournal = {Progress in Planning},
+  author = {Malczewski, Jacek},
+  urldate = {2025-10-27},
+  date = {2004-07},
+  langid = {english}
+}
+
+
+@article{thrasher2022,
+  title = {{NASA} Global Daily Downscaled Projections, {CMIP}6},
+  volume = {9},
+  issn = {2052-4463},
+  url = {https://www.nature.com/articles/s41597-022-01393-4},
+  doi = {10.1038/s41597-022-01393-4},
+  pages = {262},
+  number = {1},
+  journaltitle = {Scientific Data},
+  shortjournal = {Sci Data},
+  author = {Thrasher, Bridget and Wang, Weile and Michaelis, Andrew and Melton, Forrest and
+    Lee, Tsengdar and Nemani, Ramakrishna},
+  urldate = {2023-11-08},
+  date = {2022-06-02},
+  langid = {english}
+}

docs/paper/paper.md

@@ -0,0 +1,73 @@
+---
+title: 'LSAPy: Land Suitability Analysis in Python'
+tags:
+  - land suitability analysis
+  - land evaluation
+  - geospatial analysis
+  - GIS
+  - python
+authors:
+  - name: Baptiste Hamon
+    orcid: 0009-0007-4530-9772
+    affiliation: 1
+affiliations:
+  - name: Department of Civil and Environmental Engineering, University of Canterbury, Christchurch, New Zealand
+    index: 1
+date: 19 December 2025
+bibliography: paper.bib
+---
+
+# Summary
+
+LSAPy is a highly customizable Python library designed to streamline and enhance Land Suitability Analysis (LSA) workflows. The package implements a fuzzy-logic approach and provides two core objects - `SuitabilityCriteria` and `LandSuitabilityAnalysis` - and one module (`lsapy.standardize`) that work together to deliver a flexible and user-defined LSA framework. By relying on `xarray` objects for computation [@hoyer2017], LSAPy seamlessly integrates with the broader Python ecosystem, such as `dask` for efficient parallel processing and `matplotlib` for data visualisation. Its modular design addresses some limitations of existing LSA tools by offering greater flexibility, reproducibility, and scalability for research and practical applications.
+
+# Statement of need
+
+In the past decades, several software programs have been developed to perform land evaluation or suitability analysis, including ALES [@johnson1991], Micro-LEIS [@delarosa1992; @delarosa2004], LEIGIS [@kalogirou2002], ALSE [@elsheikh2013], and general-purpose GIS platforms (e.g., ArcGIS and QGIS) also provide functionalities for this purpose. While each of these tools offers distinct advantages, a limitation that often arises is the software-imposed constraints and the lack of freedom left to users [@elsheikh2013; @chen2022; @asaad2022]. These limitations manifest in several ways. Desktop GIS solutions, for example, often present challenges related to operating system dependency, the cost of proprietary software (e.g., ArcGIS), and difficulties in integration with broader analytical frameworks [@chen2022]. Furthermore, many specialised programs (e.g., Micro-LEIS, LEIGIS, ALSE) do not allow modification of the land characteristics used in the analysis [@elsheikh2013; @asaad2022]. This rigidity is problematic, as the predefined land characteristics may not apply to all crops or may require other parameters. Additionally, some tools (e.g., LEIGIS) support only a limited selection of crops for evaluation [@elsheikh2013].
+
+Recently, two libraries – ALUES [@asaad2022] and PyLUSAT [@chen2022] – have been developed to address some of these limitations. ALUES, an R package, supports the evaluation of 56 crops and allows the addition of new ones. While it addresses some of the limitations discussed above, it falls short in others. For instance, it relies on fixed criteria grouped into three categories (i.e., land and soil, water, and temperature) that are unmodifiable [@asaad2022]. PyLUSAT, a Python package, enables land suitability analysis using vector data, offering specific advantages such as bypassing the modifiable areal unit problem (MAUP) and the political relevance of object shape [@chen2022]. Nevertheless, raster data models have been recognized as more appropriate for LSA applications because of their area-oriented structure [@malczewski2004]. Moreover, raster-based approaches are generally more efficient for data combinations and complex calculations [@carr2007], particularly when integrating climate data, which is often distributed in netCDF format and best processed using raster routines. Converting such data to a vector format for analysis is technically feasible but suboptimal, leading to increased computational overhead and memory usage. Consequently, raster-based methods are essential for large-scale analyses, such as land suitability assessments using climate projections.
+
+Beyond these technical constraints, the lack of user flexibility in existing software introduces further limitations. First, when programs offer a restricted set of functionalities, they hinder the reproducibility of scientific results. For instance, ALSE aggregates criteria suitability using the maximum limitation method [@elsheikh2013], whereas ALUES provides only minimum, maximum, and average aggregation options [@asaad2022]. This discrepancy renders the reproduction of cross-software results impossible. Second, tools designed for specific use cases (e.g., agriculture) limit broader adoption and, in the case of free and open-source software (FOSS), may impede community engagement and growth. Finally, rigid frameworks restrict the ability to explore edge cases or out-of-the-box analyses, which are increasingly important in a rapidly changing environment.
+
+The limitations of existing software programs motivated the development of LSAPy (Land Suitability Analysis in Python), a new, highly customizable Python package supporting array-like data, such as rater and netCDF formats. Thanks to its customisation approach, frameworks used in most software programs mentioned above can be implemented in LSAPy.
+
+# Land Suitability Analysis Workflow
+
+LSAPy provides two core objects and one module that operate together to perform the land suitability analysis (LSA) according to user-defined frameworks (\autoref{fig:lsapy}).
+
+![Overview of LSAPy’s objects structures and their associated properties and methods. *`sc` is used as an abbreviation of `SuitabilityCriteria`.\label{fig:lsapy}](lsapy.png)
+
+## Standardize Module
+
+`lsapy.standardize` provides a set of standardization functions used to transforms input data (e.g., slope, annual mean temperature, annual total precipitation...) into standardized scale of suitability values ranging from 0 to 1 (\autoref{fig:lsapy}). LSAPy includes built-in functions for both discrete and continuous data. For the latter, the package follows a fuzzy-logic approach, implementing sigmoid-like and Gaussian-like membership functions previously used in LSA studies.
+
+## Suitability Criteria
+
+The `SuitabilityCriteria` defines an individual criteria used in LSA. Its `func` property refers to the standardization function, while `indicator` specifies the input data (\autoref{fig:lsapy}). The `weight` and `category` properties allow users to customise how each criteria is aggregated with others in the analysis. `is_computed` indicates whether the indicator already corresponds to suitability values and does not need further computation.
+Finally, the `compute()` method applies the standardization function to the given `indicator` to calculate the suitability score.
+
+## Land Suitability Analysis
+
+`LandSuitabilityAnalysis` is the top-level class in LSAPy, defining the LSA framework (\autoref{fig:lsapy}). All criteria for the analysis are stored in the `criteria` property. The `category`, `criteria_by_category` and `weights_by_category` properties are populated based on the defined criteria with the first one listing all unique categories, and the latter two their associated criteria and weights respectively.The `run()` method executes the LSA, with parameters specifying the level of suitability to compute (i.e., criteria, category, or overall land suitability) and the aggregation method to use. Currently, supported aggregation methods include median, mean, weighted mean, geometric mean, weighted geometric mean, and limiting factor.
+
+## Additional Features
+
+- The `stats` module offers functions for computing spatial (e.g., national, regional...) summary statistics of land use suitability.
+- LSAPy’s `open_data` function provides access to sample datasets, including soil/land data from NZGLID [@hamon2025d] and climate data from NEX-GDDP-CMIP6 [@thrasher2022] for tutorial and training purposes.
+
+## Workflow Example
+For this example, a land suitability analysis was performed using the soil and climate data provided in LSAPy, covering the New Zealand territory. Three suitability criteria were defined: slope, annual precipitation excess, and the growing temperature requirement. The first criteria was categorised under "soilTerrain", while the latter two were grouped under "climate". The indicators associated with each criteria were the slope (in degrees), annual total precipitation (in mm), and annual mean temperature (in °C) respectively, and are presented in \autoref{fig:example}. It is important to note that the chosen criteria, indicators and standardisation functions are for demonstration purposes only and do not correspond to an actual land suitability analysis for any specific crop. A comprehensive LSA would typically involve a larger number and more complex criteria.
+
+The suitability of each criteria was computed by applying the defined standardisation functions (\autoref{fig:example}). The criteria suitability were then aggregated: first, the suitability of the "soilTerrain" and "climate" categories were calculated, and then the overall land suitability was derived by combining the two categories. In this simple example, the arithmetic mean was used for all aggregation steps. The resulting land suitability map is also presented in \autoref{fig:example} and allows identifying the most suitable areas based on the defined criteria.
+
+![Workflow of the land suitability analysis example. Presented are the input indicators associated with the criteria used, the standardisation functions applied and the output suitability. The suitability of each of the criteria is shown, as well as the aggregated suitability of the categories and the final land suitability.\label{fig:example}](example.png)
+
+# Research Applications
+
+LSAPy has been used to assess the impact of climate change on apples, cherries, maize and wheat in New Zealand [@hamon2025a; @hamon2025c], and is the core component of the [New Zealand Land Use Suitability Database](https://baptistehamon.github.io/nzlusdb/).
+
+# Acknowledgements
+
+The development of LSAPy began as part of a PhD funded by the [Food Transition 2050](https://www.foodtransitions2050.ac.nz/) Joint Postgraduate School.
+
+# References

pyproject.toml

@@ -111,6 +111,7 @@ values = [
 
 [tool.codespell]
 skip = '*docs/_build, *docs/*.bib'
+ignore-words-list = 'ALSE,ALUES'
 
 [tool.deptry]
 extend_exclude = ["docs"]