wip (#11)

.github/workflows/draft-pdf.yml

@@ -5,6 +5,7 @@ on:
     branches:
       - master
       - main
+      - 11-improve-documentation
 
 jobs:
   paper:

CHANGES.md

@@ -1,12 +1,9 @@
-# 0.1.0
+# v0.1.0
 
 Major changes compared to the original `MAppleT/StocaTree`:
 
-- support Python 3 and updated dependencies
-- support Jupyter notebooks
-- modularized L-Py files
-- reimplementation of Markov in Python (previously provided by OpenAlea's StructualAnalysis)
-- replace strings with enums
-- redesign of configuration files
-- reimplement simulation output
-- bug fixes, typing and linting
+* Build system and dependencies: All outdated and unmaintained dependencies have been removed or replaced
+* Modularization: The L-Py file has been splitted up into several smaller modules
+* Markov: A Python implementation of the semi-hidden Markov chain
+* Configuration: An extended simulation and a Markov model configuration file in toml format
+* Jupyter integration: Run and visualize simulations in Jupyter lab notebooks

README.md

@@ -1,53 +1,105 @@
 # VMAppleT
 
 Apple tree simulation library using Markov chains based on StocaTree/MAppleT:
-A refactored and enhanced implementation of StocaTree. Original sources copied and modified from [openalea/incubator](https://github.com/openalea-incubator/MAppleT).
+A [refactored and enhanced](./CHANGES.md) implementation of StocaTree. Original sources copied and modified from [openalea/incubator](https://github.com/openalea-incubator/MAppleT).
 
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/jvail/vmapplet/master?urlpath=lab/tree/notebooks/simple_simulation.ipynb)
 
 
-## Major changes compared to StocaTree/MAppleT
-
-* Build system and dependencies: All outdated and unmaintained dependencies have been removed or replaced
-* Modularization: The L-Py file has been splitted up into several smaller modules
-* Markov: A Python implementation of the semi-hidden Markov chain
-* Configuration: An extended simulation and a Markov model configuration file in toml format
-* Jupyter integration: Run and visualize simulations in Jupyter lab notebooks
-
-## Install
+## Installation
 
 A local conda/miniconda installation is required.
 First clone/download the repository. The `mamba` install is optional but recommended.
 
-#### Install mamba
+### Install mamba
 
 ```sh
 conda install mamba -n base -c conda-forge
 ```
 
-#### Create environment - with a development install of VMappleT
+### Create environment - with a development install of VMappleT
 
 ```sh
 mamba env create -f binder/environment.yml
 # or
 # conda env create -f binder/environment.yml
 ```
 
-## Jupyter
+## Usage
+
+### Jupyter Lab
 
 ```sh
 conda activate vmapplet
 jupyter lab --notebook-dir=notebooks
 ```
 
-## Script
+### Console Script
 
 ```sh
 conda activate vmapplet
 python -m vmapplet vmapplet/data/simulation.toml out_folder
 ```
 
-## Usage
+### Configuration and input data
+
+There are several types of configuration files and inputs in the [data](./vmapplet/data) folder:
+
+1. A simulation [settings file](./vmapplet/data/simulation.toml) in TOML format.
+2. [Configuration files](./vmapplet/data/markov) for the parametrization of the Markov model in TOML format.
+
+#### Simulation Options
+
+Running a simulation requires an instance of class [`Options`](./vmapplet/options.py). It can be parameterized from a toml file and/or modified programatically:
+
+```py
+import toml
+from vmapplet import Options
+
+with io.open('simulation.toml') as file:
+    options = Options(**toml.loads(file.read()))
+```
+
+An instance of Options contains already all relevant parameters with reasonable defaults that may be altered programatically:
+
+```py
+from vmapplet import Options
+
+options = Options()
+options.tree.phyllotactic_angle = -144.0
+```
+
+For units and defaults take a look the [`Options`](./vmapplet/options.py) class implementation.
+
+The second important set of files are parametrizations for the [Markov](./vmapplet/markov.py) class with the following (simplified) structure:
+
+```toml
+# year relative to the simulation's first year (0)
+year = 1
+# the length ('MEDIUM' or 'LONG') of a branch
+length = 'LONG'
+
+# probabilities per Zone + 1 (see Zone enums.py)
+initial_probabilities = [1.0, ...]
+
+# probabilities tabel with Zone + 1 rows and columns
+transition_probabilities = [
+    [0.0, ...],
+]
+
+# distribution tabel with Zone + 1 rows and columns
+observation_distributions = [
+    [1.0, ..., 0.0],
+]
+
+# One description of the occupancy distribution per Zone
+[[occupancy_distributions]]
+distribution = 'NEGATIVE_BINOMIAL'
+parameter = 2.05633
+probability = 0.519757
+bounds = [4.0, +inf]
+```
 
+#### L-System
 
-## Examples
+#### Output

paper/paper.bib

@@ -16,3 +16,11 @@ @Article{Costes:2008
 doi={10.1071/FP08081},
 url={https://doi.org/10.1071/FP08081}
 }
+@Article{Jupyter:2018,
+author={Jupyter et al.},
+year={2018},
+title={Binder 2.0 - Reproducible, Interactive, Sharable Environments for Science at Scale.},
+doi={10.25080/Majora-4af1f417-011},
+journal={Proceedings of the 17th Python in Science Conference},
+url={https://doi.org/10.25080/Majora-4af1f417-011}
+}

paper/paper.md

@@ -24,8 +24,24 @@ bibliography: paper.bib
 
 # Summary
 
-VMAppleT is a refactored, modernized and updated implementation of StocaTree/MappleT [@Costes:2008] with
-support for running simulations in Jupyter notebooks to improve accessibility, extensibility and customization of the model.
+VMAppleT is a functional-structural plant model (FSPM) for apple trees based on L-Systems in Python. It is a refactored and modernized implementation of StocaTree/MAppleT [@Costes:2008] with
+support for running simulations in Jupyter notebooks. The mechanics, theoretic foundations and the application of MappleT are extensively described in [@Costes:2008].
+VMAppleT focuses on improvements in accessibility, extensibility and customization of the model implementation to facilitate future research on apple tree FSPMs:
+
+First of all the source code of StocaTree has been refactored and modernized to support Python 3.10 and to improve its readability and usability by applying both code linting and typing.
+The installation procedure has been simplified by removing dependencies on 3rd party libraries and replacing native dependencies with custom Python implementations. Documentation and tests
+included in the previous (MAppleT repository)[https://github.com/openalea-incubator/MAppleT] have been ported and extended wherever applicable.
+
+A major shortcoming of MAppleT L-System was its monolithic structure making extensions difficult. This has been addressed by splitting the L-System into several modules. Those may now either be
+customized individually, be entirely replaced by custom L-Systems or extended with additional models. The modularization is also helpful to comprehend the overall model mechanics and interaction of its
+components.
+
+The configuration and parameterization of a simulation has been simplified and ported to the widely used TOML format and corresponding Python dataclasses which implement the required parameters
+and are initialized with reasonable defaults.
+
+Supporting Jupyter notebooks by integrating Jupyter Lab including model visualization was another important goal of the reimplementation. This is particularly useful to provide users a straightforward
+access and simple examples that can even be executed and viewed via binder [@Jupyter:2018] without requiring a local installation.
+
 
 
 # Acknowledgements