PyParamGUI MVP (#5)

This MVP is made using - 
1) Anywidget for creating a widget and syncing the state between the ecmascript module frontend and python backend
2) Pydantic for model schema and validation 
3) Pyglotaran for various IO utilities

---------

Co-authored-by: Anmol <anmol-2@Anmol-Bhatias-MacBook-Air.local>
Co-authored-by: Joris Snellenburg <jsnel@users.noreply.github.com>
Co-authored-by: Sebastian Weigand <s.weigand.phy@gmail.com>

Author: 4 people

.cruft.json

@@ -5,7 +5,7 @@
   "context": {
     "cookiecutter": {
       "full_name": "Anmol Bhatia",
-      "email": "a.bhatia2@student.vu.nl",
+      "email": "anmolbhatia05@gmail.com",
       "github_username": "glotaran",
       "project_name": "PyParamGUI",
       "project_slug": "pyparamgui",

.gitignore

@@ -104,3 +104,9 @@ ENV/
 
 # IDE settings
 .vscode/
+
+examples/
+!examples/*.ipynb
+
+# MacOs OS files
+.DS_store

.pre-commit-config.yaml

@@ -20,7 +20,7 @@ repos:
         args: [--fix=lf]
 
   - repo: https://github.com/PyCQA/docformatter
-    rev: v1.7.5
+    rev: 06907d0
     hooks:
       - id: docformatter
         additional_dependencies: [tomli]
@@ -62,7 +62,7 @@ repos:
     hooks:
       - id: mypy
         exclude: "docs"
-        additional_dependencies: ["types-all"]
+        additional_dependencies: ["types-PyYAML"]
 
   ###################
   #   LINTER DOCS   #
@@ -74,13 +74,13 @@ repos:
         alias: flake8-docs
         args:
           - "--select=DOC"
-          - "--extend-ignore=DOC502"
+          - "--extend-ignore=DOC502,DOC601,DOC603,DOC101,DOC103,DOC201"
           - "--color=always"
           - "--require-return-section-when-returning-nothing=False"
           - "--allow-init-docstring=True"
           - "--skip-checking-short-docstrings=False"
         name: "flake8 lint docstrings"
-        exclude: "^(docs/|tests?/)"
+        exclude: "^(docs/|tests?/|pyparamgui/generator.py)"
         additional_dependencies: [pydoclint==0.5.3]
 
   - repo: https://github.com/econchick/interrogate
@@ -97,6 +97,7 @@ repos:
         types: [file]
         types_or: [python, pyi, markdown, rst, jupyter]
         args: [-L nnumber]
+        exclude: ^examples/
 
   - repo: https://github.com/rhysd/actionlint
     rev: "v1.7.1"

README.md

@@ -14,11 +14,7 @@
 
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 
-pyglotaran notebook widgets for teaching parameter estimation examples
-
-## Features
-
-- TODO
+A pyglotaran based jupyter notebook widget for teaching parameter estimation examples. It can simulate data, visualize it and create related model.yml, parameters.csv and dataset.nc files. It is supposed to help students learn about the basics of the pyglotaran ecosystem.
 
 ## Contributors ✨
 

pyparamgui/__init__.py

@@ -3,5 +3,17 @@
 from __future__ import annotations
 
 __author__ = """Anmol Bhatia"""
-__email__ = "a.bhatia2@student.vu.nl"
+__email__ = "anmolbhatia05@gmail.com"
 __version__ = "0.0.1"
+
+from pyparamgui.widget import Widget
+
+__all__ = ["Widget"]
+"""
+Package Usage:
+    %env ANYWIDGET_HMR=1
+    from pyparamgui import Widget
+
+    widget = Widget()
+    widget
+"""

pyparamgui/__main__.py

@@ -0,0 +1,278 @@
+"""The glotaran generator module."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from typing import Any
+from typing import TypedDict
+from typing import cast
+
+from glotaran.builtin.io.yml.utils import write_dict
+from glotaran.builtin.megacomplexes.decay import DecayParallelMegacomplex
+from glotaran.builtin.megacomplexes.decay import DecaySequentialMegacomplex
+from glotaran.builtin.megacomplexes.spectral import SpectralMegacomplex
+from glotaran.model import Model
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+def _generate_decay_model(
+    *, nr_compartments: int, irf: bool, spectral: bool, decay_type: str
+) -> dict[str, Any]:
+    """Generate a decay model dictionary.
+
+    Parameters
+    ----------
+    nr_compartments : int
+        The number of compartments.
+    irf : bool
+        Whether to add a gaussian irf.
+    spectral : bool
+        Whether to add a spectral model.
+    decay_type : str
+        The type of the decay
+
+    Returns
+    -------
+    dict[str, Any]
+        The generated model dictionary.
+    """
+    compartments = [f"species_{i+1}" for i in range(nr_compartments)]
+    rates = [f"rates.species_{i+1}" for i in range(nr_compartments)]
+
+    model: dict[str, Any] = {
+        "megacomplex": {
+            f"megacomplex_{decay_type}_decay": {
+                "type": f"decay-{decay_type}",
+                "compartments": compartments,
+                "rates": rates,
+            },
+        },
+        "dataset": {"dataset_1": {"megacomplex": [f"megacomplex_{decay_type}_decay"]}},
+    }
+    if spectral:
+        model["megacomplex"] |= {
+            "megacomplex_spectral": {
+                "type": "spectral",
+                "shape": {
+                    compartment: f"shape_species_{i+1}"
+                    for i, compartment in enumerate(compartments)
+                },
+            }
+        }
+        model["shape"] = {
+            f"shape_species_{i+1}": {
+                "type": "skewed-gaussian",
+                "amplitude": f"shapes.species_{i+1}.amplitude",
+                "location": f"shapes.species_{i+1}.location",
+                "width": f"shapes.species_{i+1}.width",
+                "skewness": f"shapes.species_{i+1}.skewness",
+            }
+            for i in range(nr_compartments)
+        }
+        model["dataset"]["dataset_1"] |= {
+            "global_megacomplex": ["megacomplex_spectral"],
+            "spectral_axis_inverted": True,
+            "spectral_axis_scale": 1e7,
+        }
+    if irf:
+        model["dataset"]["dataset_1"] |= {"irf": "gaussian_irf"}
+        model["irf"] = {
+            "gaussian_irf": {"type": "gaussian", "center": "irf.center", "width": "irf.width"},
+        }
+    return model
+
+
+def generate_parallel_decay_model(
+    *, nr_compartments: int = 1, irf: bool = False
+) -> dict[str, Any]:
+    """Generate a parallel decay model dictionary.
+
+    Parameters
+    ----------
+    nr_compartments : int
+        The number of compartments.
+    irf : bool
+        Whether to add a gaussian irf.
+
+    Returns
+    -------
+    dict[str, Any]
+        The generated model dictionary.
+    """
+    return _generate_decay_model(
+        nr_compartments=nr_compartments, irf=irf, spectral=False, decay_type="parallel"
+    )
+
+
+def generate_parallel_spectral_decay_model(
+    *, nr_compartments: int = 1, irf: bool = False
+) -> dict[str, Any]:
+    """Generate a parallel spectral decay model dictionary.
+
+    Parameters
+    ----------
+    nr_compartments : int
+        The number of compartments.
+    irf : bool
+        Whether to add a gaussian irf.
+
+    Returns
+    -------
+    dict[str, Any]
+        The generated model dictionary.
+    """
+    return _generate_decay_model(
+        nr_compartments=nr_compartments, irf=irf, spectral=True, decay_type="parallel"
+    )
+
+
+def generate_sequential_decay_model(
+    *, nr_compartments: int = 1, irf: bool = False
+) -> dict[str, Any]:
+    """Generate a sequential decay model dictionary.
+
+    Parameters
+    ----------
+    nr_compartments : int
+        The number of compartments.
+    irf : bool
+        Whether to add a gaussian irf.
+
+    Returns
+    -------
+    dict[str, Any]
+        The generated model dictionary.
+    """
+    return _generate_decay_model(
+        nr_compartments=nr_compartments, irf=irf, spectral=False, decay_type="sequential"
+    )
+
+
+def generate_sequential_spectral_decay_model(
+    *, nr_compartments: int = 1, irf: bool = False
+) -> dict[str, Any]:
+    """Generate a sequential spectral decay model dictionary.
+
+    Parameters
+    ----------
+    nr_compartments : int
+        The number of compartments.
+    irf : bool
+        Whether to add a gaussian irf.
+
+    Returns
+    -------
+    dict[str, Any]
+        The generated model dictionary.
+    """
+    return _generate_decay_model(
+        nr_compartments=nr_compartments, irf=irf, spectral=True, decay_type="sequential"
+    )
+
+
+generators: dict[str, Callable] = {
+    "decay_parallel": generate_parallel_decay_model,
+    "spectral_decay_parallel": generate_parallel_spectral_decay_model,
+    "decay_sequential": generate_sequential_decay_model,
+    "spectral_decay_sequential": generate_sequential_spectral_decay_model,
+}
+
+available_generators: list[str] = list(generators.keys())
+
+
+class GeneratorArguments(TypedDict, total=False):
+    """Arguments used by ``generate_model`` and ``generate_model``.
+
+    Parameters
+    ----------
+    nr_compartments : int
+        The number of compartments.
+    irf : bool
+        Whether to add a gaussian irf.
+
+    See Also
+    --------
+    generate_model
+    generate_model_yml
+    """
+
+    nr_compartments: int
+    irf: bool
+
+
+def generate_model(*, generator_name: str, generator_arguments: GeneratorArguments) -> Model:
+    """Generate a model.
+
+    Parameters
+    ----------
+    generator_name : str
+        The generator to use.
+    generator_arguments : GeneratorArguments
+        Arguments for the generator.
+
+    Returns
+    -------
+    Model
+        The generated model
+
+    See Also
+    --------
+    generate_parallel_decay_model
+    generate_parallel_spectral_decay_model
+    generate_sequential_decay_model
+    generate_sequential_spectral_decay_model
+
+    Raises
+    ------
+    ValueError
+        Raised when an unknown generator is specified.
+    """
+    if generator_name not in generators:
+        msg = (
+            f"Unknown model generator '{generator_name}'. "
+            f"Known generators are: {list(generators.keys())}"
+        )
+        raise ValueError(msg)
+    model = generators[generator_name](**generator_arguments)
+    return Model.create_class_from_megacomplexes(
+        [DecayParallelMegacomplex, DecaySequentialMegacomplex, SpectralMegacomplex]
+    )(**model)
+
+
+def generate_model_yml(*, generator_name: str, generator_arguments: GeneratorArguments) -> str:
+    """Generate a model as yml string.
+
+    Parameters
+    ----------
+    generator_name : str
+        The generator to use.
+    generator_arguments : GeneratorArguments
+        Arguments for the generator.
+
+    Returns
+    -------
+    str
+        The generated model yml string.
+
+    See Also
+    --------
+    generate_parallel_decay_model
+    generate_parallel_spectral_decay_model
+    generate_sequential_decay_model
+    generate_sequential_spectral_decay_model
+
+    Raises
+    ------
+    ValueError
+        Raised when an unknown generator is specified.
+    """
+    if generator_name not in generators:
+        msg = (
+            f"Unknown model generator '{generator_name}'. "
+            f"Known generators are: {list(generators.keys())}"
+        )
+        raise ValueError(msg)
+    model = generators[generator_name](**generator_arguments)
+    return cast(str, write_dict(model))