📚Improve documentation - rework getting-started notebook.

.gitignore

@@ -185,7 +185,7 @@ benchmark/.asv
 comparison-results
 comparison-results-current
 
-# Quickstart docs output files
-docs/source/notebooks/quickstart/quickstart_project/data
-docs/source/notebooks/quickstart/quickstart_project/results
-docs/source/notebooks/quickstart/quickstart_project/project.gta
+# getting_started docs output files
+docs/source/notebooks/getting_started/my_project/data
+docs/source/notebooks/getting_started/my_project/results
+docs/source/notebooks/getting_started/my_project/project.gta

AUTHORS.rst

@@ -2,26 +2,39 @@
 Authors
 =======
 
-Development Lead
-----------------
-* Joern Weissenborn <[email protected]>
-* Joris Snellenburg <[email protected]>
+🏆 Core Team
+-------------
+* 💡📝 Joern Weissenborn <[email protected]> (`@joernweissenborn <https://github.com/joernweissenborn>`_)
+* 🛠️📝 Joris Snellenburg <[email protected]> (`@jsnel <https://github.com/jsnel>`_)
+* 🛠️📝 Sebastian Weigand <[email protected]> (`@s-weigand <https://github.com/s-weigand>`_)
 
-Contributors
-------------
-* Sebastian Weigand <[email protected]>
+🙏 Special Thanks
+------------------
+* 🙏 Stefan Schuetz
+* 🙏 Sergey P. Laptenok
 
-Special Thanks
---------------
-* Stefan Schuetz
-* Sergey P. Laptenok
+🎓 Supervision
+---------------
+* 🎓🙏 dr. Ivo H.M. van Stokkum <[email protected]> (`University profile <https://research.vu.nl/en/persons/ihm-van-stokkum>`_)
 
-Supervision
---------------
-* **dr. Ivo H.M. van Stokkum** <[email protected]> (`University profile <https://research.vu.nl/en/persons/ihm-van-stokkum>`_)
+📖 Emoji Legend
+----------------
+* 💡 **Creator**: Creator of the package core
+* 📝 **Author**: Significant contributions to the package
+* 🛠️ **Maintainer**: Responsible for maintaining the package
+* 🎓 **Supervisor**: Provided guidance and supervision
+* 🙏 **Contributor**: Contributed code or documentation
 
-Original publications
+📚 Core publications
 ---------------------
-1. Joris J. Snellenburg, Sergey Laptenok, Ralf Seger, Katharine M. Mullen, Ivo H. M. van Stokkum. "Glotaran: A Java-Based Graphical User Interface for the R Package TIMP". Journal of Statistical Software (2012), Volume 49, Number 3, Pages: 1–22. URL https://dx.doi.org/10.18637/jss.v049.i03
-2. Katharine M. Mullen, Ivo H. M. van Stokkum. "TIMP: An R Package for Modeling Multi-way Spectroscopic Measurements". Journal of Statistical Software (2007), Volume 18, Number 3, Pages 1-46, ISSN 1548-7660. URL https://dx.doi.org/10.18637/jss.v018.i03
-3. Ivo H. M. van Stokkum, Delmar S. Larsen, Rienk van Grondelle, "Global and target analysis of time-resolved spectra". Biochimica et Biophysica Acta (BBA) - Bioenergetics (2004), Volume 1657, Issues 2–3, Pages 82-104, ISSN 0005-2728. URL https://doi.org/10.1016/j.bbabio.2004.04.011
+*The publications that describe fundamental aspects of the pyglotaran framework.*
+
+1. Ivo H. M. van Stokkum, Joern Weißenborn, Sebastian Weigand, Joris Snellenburg. "pyglotaran: a lego-like Python framework for global and target analysis of time-resolved spectra". Photochem Photobiol Sci 22, 2413–2431 (2023). DOI: https://doi.org/10.1007/s43630-023-00460-y
+
+📚 Seminal papers
+------------------
+*The publications that ultimately inspired the creation of pyglotaran.*
+
+1. Joris J. Snellenburg, Sergey Laptenok, Ralf Seger, Katharine M. Mullen, Ivo H. M. van Stokkum. "Glotaran: A Java-Based Graphical User Interface for the R Package TIMP". Journal of Statistical Software (2012), Volume 49, Number 3, Pages: 1–22. DOI: https://dx.doi.org/10.18637/jss.v049.i03
+2. Katharine M. Mullen, Ivo H. M. van Stokkum. "TIMP: An R Package for Modeling Multi-way Spectroscopic Measurements". Journal of Statistical Software (2007), Volume 18, Number 3, Pages 1-46, ISSN 1548-7660. DOI: https://dx.doi.org/10.18637/jss.v018.i03
+3. Ivo H. M. van Stokkum, Delmar S. Larsen, Rienk van Grondelle, "Global and target analysis of time-resolved spectra". Biochimica et Biophysica Acta (BBA) - Bioenergetics (2004), Volume 1657, Issues 2–3, Pages 82-104, ISSN 0005-2728. DOI: https://doi.org/10.1016/j.bbabio.2004.04.011

INSTALLATION.md

@@ -0,0 +1,196 @@
+# Installation Guide for pyglotaran
+
+This guide provides step-by-step instructions for installing **pyglotaran** on Windows, macOS, and Linux systems. It starts with installing pyglotaran if you already have Python installed, ensuring the use of virtual environments to keep your system clean. If you don't have Python installed yet, we'll guide you through installing Python on your system.
+
+## Prerequisites
+
+Before installing pyglotaran, ensure you have:
+
+- **Python 3.10 or higher** installed on your system.
+- Basic familiarity with command-line interfaces.
+
+### Check if Python is Installed
+
+Open your terminal or command prompt and run:
+
+```shell
+python --version
+```
+
+or
+
+```
+python3 --version
+```
+
+If Python is installed, this command will display the Python version number.
+
+- If the version is 3.10 or higher, proceed to installing pyglotaran.
+- If you see a lower version number or receive an error message, proceed to Installing Python on Your System.
+
+## Installing pyglotaran
+
+💡 _It is **recommended** to use a virtual environment to install pyglotaran into, to avoid possible conflicts with other Python packages and to keep your system Python environment clean._
+
+### Step 1: Create a Project Directory
+
+Create a new project folder. This could also be a folder downloaded from the [examples](https://github.com/glotaran/pyglotaran-examples).
+
+### Step 2: Create a Virtual Environment
+
+Create a virtual environment named venv.
+
+For Windows:
+
+```shell
+python -m venv venv
+```
+
+<sub>(on MacOS/Linux) you may have to use `python3` instead of `python`.</sub>
+
+### Step 3: Activate the Virtual Environment
+
+Within your project folder run the following.
+
+For Windows:
+
+```shell
+venv\Scripts\activate
+```
+
+For MacOS/Linux:
+
+```shell
+source venv/bin/activate
+```
+
+After activation, your command prompt should be prefixed with (venv).
+
+### Step 4: Install pyglotaran
+
+Install pyglotaran using pip
+
+```shell
+pip install pyglotaran
+```
+
+### Step 5: Verify the Installation
+
+To verify that pyglotaran is installed correctly, run:
+
+```shell
+python -c "import pyglotaran; print(pyglotaran.__version__)"
+```
+
+If the installation was successful, this command will print the version number of pyglotaran.
+
+## Installing Python on Your System
+
+If you don't have Python installed, follow the instructions below for your operating system.
+
+### Windows
+
+#### Option 1: Install Python via the Microsoft Store
+
+1. Open the Microsoft Store app.
+2. Search for Python and select the latest version (Python 3.10 or higher).
+3. Click Get or Install.
+
+**\*Note**: This method installs Python only for the current user and doesn't require administrative privileges.\*
+
+#### Option 2: Install Python from python.org
+
+1. Go to the official Python website.
+2. Download the latest Python installer (Python 3.10 or higher).
+3. Run the installer:
+
+- Check the box that says "Add Python to PATH".
+- Choose "Install Now" for a default installation.
+
+## macOS
+
+#### Option 1: Install Python via Homebrew
+
+1. Install Homebrew if you haven't already:
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+2. Install Python:
+
+```bash
+brew install python
+```
+
+### Option 2: Install Python from python.org
+
+1. Visit the official Python website.
+2. Download the latest Python installer (Python 3.10 or higher).
+3. Run the installer and follow the prompts.
+
+## Linux
+
+### Ubuntu/Debian
+
+Update the package list:
+
+```
+sudo apt update
+```
+
+Install Python and pip:
+
+```
+sudo apt install python3 python3-venv python3-pip
+```
+
+### Other Distributions
+
+Refer to your distribution's package manager documentation to install Python 3.10 or higher, python3-venv, and python3-pip.
+
+# Next Steps
+
+Now that you have Python and pyglotaran installed, you can start using pyglotaran for your data analysis.
+
+## Using pyglotaran
+
+pyglotaran is designed to be used within Python scripts or Jupyter Notebooks. It involves defining your analysis scheme, which includes:
+
+- A model: Defines the kinetic scheme of your system.
+- Parameters: Initial guesses and constraints for the model parameters.
+- Experimental data: The data you want to fit.
+
+You then use pyglotaran to optimize the model parameters to fit your data.
+
+### Install Jupyter Notebook (Optional)
+
+If you plan to use pyglotaran within Jupyter Notebooks, install Jupyter Notebook in your virtual environment:
+
+```bash
+pip install jupyterlab
+```
+
+Then, start the Jupyter Notebook server:
+
+```bash
+jupyter lab
+```
+
+This will open the Jupyter Notebook interface in your web browser.
+
+## Examples and Tutorials
+
+We have prepared comprehensive examples in the form of Jupyter Notebooks in the pyglotaran-examples repository. These examples illustrate how to use the framework for various use cases.
+
+To get started:
+
+1. Clone or [download](https://github.com/glotaran/pyglotaran-examples/archive/refs/heads/main.zip) the repository:
+
+   ```bash
+   git clone https://github.com/glotaran/pyglotaran-examples.git
+   ```
+
+2. Navigate to the example that best matches your use case.
+
+3. Run the Jupyter Notebook to see pyglotaran in action.

MANIFEST.in

@@ -3,6 +3,7 @@ include CONTRIBUTING.rst
 include changelog.md
 include LICENSE
 include README.md
+include NOTICE.md
 setup.cfg
 setup.py
 

NOTICE.md

@@ -0,0 +1,27 @@
+# Usage notice for scientists
+
+## Disclaimer
+
+This software package is made available as an early access release, to the advantage of the (scientific) community who wishes to make use of it before it has fully matured, but without any warranties.
+
+Anyone using this package for serious work - scientists and academic users in particular - are cautioned, and treat it as any other instrument or tool that requires calibration or validation. Also be prepared for some refactoring of models or analysis specifications, sometime down the line.
+
+## Scientific usage
+
+That said, the pyglotaran package has been used in several peer-reviewed scientific publications, and it has been partially cross-validated against comparable software, such as the [R-package TIMP](https://dx.doi.org/10.18637/jss.v018.i03), and the TIM software described in [this publication](https://doi.org/10.1016/j.bbabio.2004.04.011) ([DOI: 10.1016/j.bbabio.2004.04.011](https://doi.org/10.1016/j.bbabio.2004.04.011)).
+
+The examples used in this validation process can be obtained from the [pyglotaran-examples repository](https://github.com/glotaran/pyglotaran-examples).
+
+Since the early access version `v0.6.0` it was used in scientific teaching by a number of students in the Photosynthesis and Energy course from 2022-2024 under the supervision of [dr. Ivo van Stokkum](https://www.nat.vu.nl/~ivo/) ([profile](https://research.vu.nl/en/persons/ihm-van-stokkum), github: [ism200](https://github.com/ism200/)). Course material can be found here: [ism200\PE2022](https://github.com/ism200/PE2022/)
+
+## Quality Control
+
+<!-- placeholder text -->
+
+As pyglotaran developers we strive to deliver high quality but also very reliable software, software you can trust as the basis for your scientific publications. How do we do this?
+
+The development process follows best practices in software engineering, we use git, automated testing, continuous integration, and code reviews. All code changes must pass a comprehensive (unit) test suite and is reviewed by at least one core maintainers before being merged. We use GitHub Actions to automatically run tests, linting, and other quality checks on every pull request and code push.
+
+But more importantly for quality assurance is the pyglotaran-validation framework. As described in Sebastian Weigand's MSc thesis, this framework allows for automated validation of pyglotaran's results against established known good results. It decouples result validation from the main project, allowing us to easily compare results from earlier with newer versions. The validation framework compares pyglotaran outputs to manually validated reference results (or so-called gold standard).
+
+<!-- end of placeholder text -->