FASTEN-cli 1.0.0__py2.py3-none-any.whl

FASTEN/tune.py

@@ -0,0 +1,92 @@
+from .common import os, json
+from .plot import plot_train, plot_predict
+from .train import Trainer
+from .predict import Predictor
+from copy import deepcopy
+import optuna, warnings
+
+warnings.filterwarnings("ignore", category = optuna.exceptions.ExperimentalWarning)
+
+
+class Tuner:
+    def __init__(self, trainer: Trainer):
+        self.trainer = trainer
+        self.model = trainer.model
+        self.config = trainer.model.config
+        self.study: optuna.Study = None
+
+    def dump_trials(self, output_dir: str):
+        trials_file = f"{output_dir}/trials.tsv" 
+        trial_data = self.study.trials_dataframe().sort_values(by = "value")
+        trial_data.to_csv(trials_file, sep = "\t", index = False)
+
+        best_params = self.study.best_trial.params
+        for arg, value in self.config["model"].items():
+            if isinstance(value, list): self.config["model"][arg] = best_params[arg]
+        for arg, value in self.config["train"].items():
+            if isinstance(value, list): self.config["train"][arg] = best_params[arg]
+        with open(f"{output_dir}/config.json", "w") as file:
+            json.dump(self.config, file, indent = 4)
+
+    def load_study(self, output_dir: str, study_name: str = "tune_data"):
+        self.output_dir = output_dir
+        if not os.path.exists(output_dir): 
+            os.mkdir(output_dir)
+            os.mkdir(f"{output_dir}/plots")
+            os.mkdir(f"{output_dir}/plots/trials")
+        storage_name = f"sqlite:///{output_dir}/{study_name}.db"
+        sampler = optuna.samplers.TPESampler(n_startup_trials = 20, multivariate = True)
+        self.study = optuna.create_study(study_name = study_name, storage = storage_name, 
+            load_if_exists = True, direction = "minimize", sampler = sampler)       
+    
+    def execute(self, n_trials: int, duplicates: bool):
+        while len(self.study.get_trials()) < n_trials:
+            objective = Objective(self, duplicates)
+            self.study.optimize(objective, n_trials = 1)
+
+
+class Objective:
+    def __init__(self, tuner: Tuner, unique: bool):
+        self.tuner, self.trainer = tuner, tuner.trainer
+        self.unique = unique
+        self.trial_dir = f"{self.tuner.output_dir}/plots/trials"
+
+    def sample(self, trial) -> tuple[dict, dict]:
+        trial_model, trial_train = dict(), dict()
+        for arg, value in self.tuner.config["model"].items():
+            if not isinstance(value, list): trial_model[arg] = value
+            else: trial_model[arg] = trial.suggest_categorical(arg, value)
+        for arg, value in self.tuner.config["train"].items():
+            if not isinstance(value, list): trial_train[arg] = value
+            else: trial_train[arg] = trial.suggest_categorical(arg, value)
+        if "rand_seed" not in trial_train or trial_train["rand_seed"] is None:
+            trial_train["rand_seed"] = trial.number
+        return trial_model, trial_train
+    
+    def get_duplicate(self, trial) -> tuple[bool, int, float]:
+        if not self.unique: return False, None, None
+        for prev in trial.study.trials:
+            if prev.number != trial.number and prev.params == trial.params:
+                return True, prev.number, prev.value
+        return False, None, None
+
+    def __call__(self, trial) -> float: 
+        trial_model, trial_train = self.sample(trial)
+        duplicate, number, value = self.get_duplicate(trial)
+        if duplicate: 
+            print(f"Trial {trial.number} is a duplicate of trial {number} with value {value}.")
+            return value
+        
+        self.tuner.model.validate_args(trial_model, trial_train)
+        try: self.trainer.execute()
+        except ValueError: 
+            message = "Training diverged: loss is NaN (possible exploding gradients)"
+            raise optuna.exceptions.TrialPruned(message)
+        
+        plot_train(self.trainer, f"{self.trial_dir}/trial_{trial.number}")
+        predictor = Predictor(self.tuner.model, deepcopy(self.trainer.test.dataset))
+        mse, kld, nll = plot_predict(predictor, f"{self.trial_dir}/trial_{trial.number}")
+        match self.tuner.model.args.loss_func:
+            case "MSE": return mse.mean().mean()
+            case "KLD": return kld.mean().mean()
+            case _: return nll.mean().mean()

FASTEN/utils.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+from .common import np, pd, torch
+from .config import ModelInput
+
+
+class Scaler():
+    def __init__(self):
+        self.min = None
+        self.max = None
+        self.range = None
+        self.fitted = False
+
+    def fit(self, data):
+        if isinstance(data, pd.DataFrame):
+            self.min = np.min(data.values, axis = 0)
+            self.max = np.max(data.values, axis = 0)
+        if isinstance(data, torch.Tensor):
+            self.min = data.min(dim = 0).values.numpy()
+            self.max = data.max(dim = 0).values.numpy()
+        self.range = self.max - self.min
+        self.range[self.range == 0] = 1.0
+        self.fitted = True
+
+    def transform(self, data):
+        if not self.fitted: self.fit(data)
+        data -= self.min
+        data /= self.range
+        if isinstance(data, pd.DataFrame): data.clip(0, 1)
+        if isinstance(data, torch.Tensor): torch.clamp(data, 0, 1)
+
+    def inverse_transform(self, data):
+        data *= self.range
+        data += self.min
+
+
+class Encoder():
+    def __init__(self, inputs: dict[str, ModelInput]): 
+        self.inputs = inputs
+            
+    def fit(self, data: pd.Series) -> bool:
+        self.labels, self.names = [], []
+        self.origins, self.strings = [], []
+        for i, origin in enumerate(self.inputs.values()):
+            if origin.type != "string": continue
+            for string in data[origin.label].unique():
+                self.labels.append(f"{origin.label}_{string}")
+                self.names.append(f"{origin.name}: {string.capitalize()}")
+                self.origins.append(i)
+                self.strings.append(string)
+        if len(self.strings) != len(set(self.strings)):
+            raise AssertionError("Set of strings must be disjoint for all categorical inputs.")
+        return len(self.strings) > 0
+    
+    def transform(self, data: pd.Series):
+        if not self.fit(data): return
+        col = {string: i for i, string in enumerate(self.strings)}
+        values = np.zeros((data.shape[0], len(self.labels)))
+        for origin in self.inputs.values():
+            if origin.type != "string": continue
+            for row, string in enumerate(data[origin.label]):
+                values[row, col[string]] = 1
+                label = self.labels[col[string]]
+                name = self.names[col[string]]
+                self.inputs[label] = ModelInput(label, name, "integer")
+            data.drop(columns = origin.label, inplace = True)
+            self.inputs.pop(origin.label)
+        data[self.labels] = pd.DataFrame(values, dtype = float, index = data.index)

fasten_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: FASTEN-cli
+Version: 1.0.0
+Project-URL: Homepage, https://github.com/k1jackson/FASTEN
+Project-URL: Bug Tracker, https://github.com/k1jackson/FASTEN/issues
+Project-URL: Config Designer, https://k1jackson.github.io/FASTEN/
+License-File: LICENSE.md
+Requires-Dist: k-means-constrained
+Requires-Dist: matplotlib
+Requires-Dist: numpy>=2.1.1
+Requires-Dist: optuna
+Requires-Dist: pandas
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich
+Requires-Dist: scikit-learn
+Requires-Dist: scipy>=1.14.0
+Requires-Dist: torch
+Description-Content-Type: text/markdown
+
+# FASTEN
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
+[![Version](https://img.shields.io/badge/version-1.0.0-brightgreen.svg)](CHANGELOG.md)
+
+
+<!-- Explain the *what* and *why* of your project in 2–4 sentences.
+     Answer: What problem does it solve? Who is it for? Why does it exist? -->
+
+FASTEN is a flexible and user-friendly framework for building PyTorch-based deep learning emulators for epidemic simulations with stochastic outputs. FASTEN provides three intuitive modules to (1) train deep neural networks on simulation data, (2) select optimal hyperparameters, and (3) generate predictions from unseen inputs. 
+
+
+## Installation
+
+
+FASTEN can be installed via ```pip```:
+
+```bash
+pip install fasten-cli
+```
+
+## Usage
+
+There are two primary components to FASTEN: the [configuration file designer](https://k1jackson.github.io/FASTEN/) and the command line tool.
+
+### Configuration File Designer
+Before executing a FASTEN, the user must construct a workflow configuration file that outlines the simulation data format and training hyperparameters. The [configuration file designer](https://k1jackson.github.io/FASTEN/) guides users through this process with contextual instructions and validation checks.
+
+### Command Line Tool
+The FASTEN workflow decomposes the model emulation process into three phases: (1)training, (2) hyperparameter tuning, and (3) output prediction. Each phase is invoked through a dedicated command line module, with a shared configuration file governing the underlying behavior. The command line tool can used as follows:
+
+**Training:**
+
+```bash
+usage: FASTEN train [-h] -c CONFIG -i INPUT [-o OUTPUT] [-m MODEL]
+
+options:
+  -h, --help           show this help message and exit
+  -c, --config CONFIG  JSON file defining configuration parameters
+  -i, --input INPUT    TSV file with simulation data
+  -o, --output OUTPUT  Folder to output model and figures (default: outputs)
+  -m, --model MODEL    ZIP file containing initial model (default: None)
+```
+
+**Hyperparameter Tuning:**
+
+```bash
+usage: FASTEN tune [-h] -c CONFIG -i INPUT [-o OUTPUT] [-n TRIALS] [--unique]
+
+options:
+  -h, --help           show this help message and exit
+  -c, --config CONFIG  JSON file defining configuration parameters
+  -i, --input INPUT    TSV file with simulation data
+  -o, --output OUTPUT  Folder to output optimal configs and figures (default: outputs)
+  -n, --trials TRIALS  Total number of optimation trials (default: 100)
+  --unique             Prevents re-training with duplicate hyperparameter sets (default: False)
+```
+
+**Output Prediction:**
+
+```bash
+usage: FASTEN predict [-h] -m MODEL -i INPUT [-o OUTPUT] [-n RUNS]
+
+options:
+  -h, --help           show this help message and exit
+  -m, --model MODEL    ZIP file containing model
+  -i, --input INPUT    TSV file with simulation inputs
+  -o, --output OUTPUT  TSV file to output predicted simulation data (default: outputs.tsv)
+  -n, --runs RUNS      Number of simulation runs per input (default: 0)
+```

fasten_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+FASTEN/__init__.py,sha256=e-T0h8j5pOz4g3c9sp-sQVnMGzuWSm6Dv4h_UAXigLE,188
+FASTEN/cli.py,sha256=ncH8WWFEoEYiUlmGKSuxEJxfuFinQeATeJuLRaoNYYs,5139
+FASTEN/common.py,sha256=HZ4iB68x2oq7yKz_gwpKNACizCKdEKkvXnPk2CQBtnU,123
+FASTEN/config.py,sha256=hh6GpUTavZlqzipaXykidjcb0PgIjTL9bOYwbCezHD4,4858
+FASTEN/data.py,sha256=r4kSVvkpO1abNObzZaef2AaGktc--jYYcZjZW2AOd4Q,6141
+FASTEN/estimate.py,sha256=svQVENGB0M_vxX_jh4WdusJXibEs9_QE28KchzfIMSY,6711
+FASTEN/learn.py,sha256=aTazbtU4-W4pEBy8qCMRDYkOKmENgu16yiA4LQrDSf0,7933
+FASTEN/model.py,sha256=-aS3qBci-LOIn1MjKLQxr-R4rcUxbN4_hqCI8RKE5iM,7864
+FASTEN/param.py,sha256=AtF0zuSsA_Dn4H89cN6BRZqv0NdNSXWaupv3qCJVahQ,5951
+FASTEN/plot.py,sha256=-blUaho6X_4gY5AmZK4FTeMAzVr-Veds4ABug-VbQFE,10261
+FASTEN/predict.py,sha256=b0LJDiVnfA4ga3BVOljAkyj5Xs8oe1_EMX6BTRTq6MY,3084
+FASTEN/train.py,sha256=K6hsDpSGWYZi-jsISSZuTr-keaE0gjrjN7b80_Oc-uc,3940
+FASTEN/tune.py,sha256=ltZB9CweGP3AkzFbn4SEQAVYsXTZ1wCfW9wcyKgk7UM,4345
+FASTEN/utils.py,sha256=MMq7Bs9VsuEcYjpDvkZUTh2KFl9-_7OmSOik95Wtj-w,2615
+fasten_cli-1.0.0.dist-info/METADATA,sha256=XTMnePdGxEuIxIlxviuNg0sKEjIHLzyAtm3UMMDGGUw,3586
+fasten_cli-1.0.0.dist-info/WHEEL,sha256=VX-VJ7c6dw9Ge3EqJIbA6W3pOUbz24SnnGGFNr55jY4,105
+fasten_cli-1.0.0.dist-info/entry_points.txt,sha256=brVh-WK-yszMifsiSc3uCLQs3srzXjlvObGR0Xq1IqE,43
+fasten_cli-1.0.0.dist-info/licenses/LICENSE.md,sha256=u5ofZFWS6UIMv9Qaf1Yjvuouqd4xatYjLqA4Ejtxv7Q,1069
+fasten_cli-1.0.0.dist-info/RECORD,,

fasten_cli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any

fasten_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+FASTEN = FASTEN.cli:main

fasten_cli-1.0.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kate Jackson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.