ws3 (presubmission inquiry)

[gparadis]

Submitting Author: Name (@gparadis)
Package Name: ws3
One-Line Description of Package: ws3 (Wood Supply Simulation System) is a Python package for modeling landscape-level wood supply planning problems
Repository Link (if existing): https://github.com/UBC-FRESH/ws3
EiC: @coatless

---

Code of Conduct & Commitment to Maintain Package

• I agree to abide by pyOpenSci's Code of Conduct during the review process and in maintaining my package after should it be accepted.
• I have read and will commit to package maintenance after the review as per the pyOpenSci Policies Guidelines.

Description

• Include a brief paragraph describing what your package does:

ws3 is an open-source Python package that provides a modular framework for forest estate modeling and wood supply simulation. It enables researchers and practitioners to analyze and optimize forest management strategies under different ecological and policy scenarios. As a transparent and extensible alternative to commercial tools like Remsoft Woodstock, ws3 advances reproducible science in forestry and land-use modeling. Its architecture facilitates collaborative development, standardized data flows, and integration with broader decision support pipelines.

Community Partnerships

We partner with communities to support peer review with an additional layer of
checks that satisfy community requirements. If your package fits into an
existing community please check below:

• Astropy: My package adheres to Astropy community standards
• Pangeo: My package adheres to the Pangeo standards listed in the pyOpenSci peer review guidebook

Scope

• Please indicate which category or categories this package falls under:

  • Data retrieval
  • Data extraction
  • Data processing/munging
  • Data deposition
  • Data validation and testing
  • Data visualization
  • Workflow automation
  • Citation management and bibliometrics
  • Scientific software wrappers
  • Database interoperability

Domain Specific

• Geospatial
• Education

---

• Explain how and why the package falls under these categories (briefly, 1-2 sentences). For community partnerships, check also their specific guidelines as documented in the links above. Please note any areas you are unsure of:

Workflow automation: ws3 automates complex simulation and optimization workflows for forest estate modeling. While there is no practical manual alternative to many of its core modeling functions, ws3 structures these workflows using modular Python components that support transparent, reproducible planning and scenario analysis. In this sense, ws3 enables users to automate, inspect, and extend workflows that would otherwise be available only through proprietary software such as Remsoft Woodstock.

Scientific software wrapper: ws3 exposes reusable Python interfaces to core simulation and optimization logic, enabling integration with broader scientific pipelines (e.g., scenario generators, visualization tools, or external simulators). Unlike monolithic black-box tools, ws3 supports introspection and reuse by design.

Data visualization: While not the primary focus, ws3 includes utilities to visualize modeling inputs, landbase structure, and simulated outputs in a geospatial context using open-source tools like geopandas and matplotlib.

Geospatial: Forest estate models are inherently spatial. ws3 handles geospatial data inputs and outputs using standard formats (e.g., GeoJSON, raster), integrates with GIS workflows, and supports spatial partitioning of forested landscapes into planning units and yield regions.

• Who is the target audience and what are the scientific applications of this package?

The target audience includes researchers and professionals in forest management, ecological modeling, carbon accounting, and land-use policy. ws3 supports scientific applications such as sustainable harvest planning, habitat impact analysis, carbon offset scenario testing, and long-term forest policy evaluation.

• Are there other Python packages that accomplish similar things? If so, how does yours differ?

There are no other open-source Python packages that provide equivalent functionality for forest estate modeling. Existing alternatives such as Remsoft Woodstock or Patchworks are proprietary or closed-source, limiting transparency, reproducibility, and extensibility. ws3 is unique in offering a flexible, inspectable, and open framework for simulating and optimizing strategic forest planning problems.

• Any other questions or issues we should be aware of:

The package is relatively large and complex compared to many pyOpenSci submissions. However, we believe it fits within scope due to its modular architecture, test coverage, and potential to serve as a reusable modeling toolkit in the domain of forest and land-use science.

P.S. Have feedback/comments about our review process? Leave a comment here

[coatless]

Hi @gparadis 👋

Great to see UBC research appear here!

I think this is definitely in scope and novel. So, please feel free to go ahead and request a full review when you desire.

I will mention a few quick notes:

Package Dependency

Due to changes in numpy, please verify "numpy>2" works or consider limiting scope to numpy>=1.24, numpy<2

https://github.com/UBC-FRESH/ws3/blob/d17dbdbd77abfa65d1ae570b602f0911dcb72ec7/pyproject.toml#L13C3-L13C16
README

README

Please add installation instructions:

https://www.pyopensci.org/python-package-guide/documentation/repository-files/readme-file-best-practices.html#installation-instructions

Please show a brief example of the package in action:

https://www.pyopensci.org/python-package-guide/documentation/repository-files/readme-file-best-practices.html#brief-demonstration-of-how-to-use-the-package

Please add a community section:

https://www.pyopensci.org/python-package-guide/documentation/repository-files/readme-file-best-practices.html#a-community-section-with-links-to-contributing-guide-code-of-conduct

Please update the repository information to add the readthedocs webpage.

https://ws3.readthedocs.io/en/latest/index.html

Should be here:

https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics#adding-topics-to-your-repository

(Sorry, there's only a "topics" help page for showing this... But, it's in the same location!)

Package website

Please try to organize the landing page with:

https://www.pyopensci.org/python-package-guide/documentation/write-user-documentation/get-started.html#four-elements-of-a-good-open-source-documentation-landing-page

Example: https://www.fatiando.org/verde/latest/

Please clearly label the API Reference:

ws3 Package and Data Preparation

https://ws3.readthedocs.io/en/latest/aboutws3.html

We suggest placing this at the end of the navigation bar after the gallery of examples.

Please make available a way to obtain example data, e.g. data/shp/tsa24_clipped.shp/stands.shp. This could be through a function or a simple bash script that could be run by a user to download and setup the data in an expected format.

https://ws3.readthedocs.io/en/latest/examples/010_ws3_model_example-fromscratch.html#Set-up-Python-environment

Action

The package is found to be in-scope and novel.

However, additional steps should be taken to address the README file and website requirements. We cannot send the package onto a later stage until these issues are addressed as our reviewers and your future users will need to be able to more easily navigate the documentation.

You can view the initial checklist for EiC (requirement to begin editor assignment) here:

https://www.pyopensci.org/software-peer-review/how-to/editor-in-chief-guide.html#editor-checklist-template

Please feel free to create a new issue with our full review template:

https://github.com/pyOpenSci/software-submission/issues/new?template=submit-software-for-review.md

We'll close this issue ticket in the next 4 days.