docs: refresh README

2026-07-27 15:24:01 +02:00
parent 3a642c53a0
commit 1799308586
1 changed files with 73 additions and 0 deletions
@@ -0,0 +1,73 @@
+# Temperature-based fertility prediction thesis
+
+Source material and research code for a master's thesis on body-core-temperature-based fertility prediction with machine learning. The thesis evaluates recurrent, transformer-based, and convolutional variants using retrospective sensor-cycle data. It is research material, not a clinical product or medical guidance.
+
+## Status, privacy, and reproducibility
+
+The repository contains neither a Python dependency manifest/lock file nor an environment bootstrap, and no runnable test suite was found. Full reproduction requires private or external cycle data, access to the `vsm_datascience_common` package and its cycle database, LMDB storage, and likely GPU/SLURM infrastructure. Do not add health/cycle data, database credentials, or `.env` contents to the repository or documentation.
+
+The thesis itself notes limitations including retrospective labels, noisy real-world data, and use of temperature as a single modality. Results and configurations should not be interpreted as validated clinical performance.
+
+## Repository layout
+
+- `thesis/main.tex` — thesis document; section sources are under `thesis/sections/` and figures under `thesis/resources/figures/`.
+- `main.bib` — bibliography used by the thesis.
+- `code/` — dataset creation, training, evaluation, and job-launch scripts.
+- `code/configs/` — experiment and model-run configuration modules, including LSTM runs.
+- `presentation/` and `expose/` — supporting presentation and exposé material.
+
+## Build the thesis
+
+Run LaTeX commands from `thesis/`, because `main.tex` resolves the bibliography as `../main.bib` and figures relative to that directory. A LaTeX installation with `biber` is required (`biblatex` is configured with `backend=biber`). A conventional compilation sequence is:
+
+```sh
+cd thesis
+pdflatex main.tex
+biber main
+pdflatex main.tex
+pdflatex main.tex
+```
+
+No repository Makefile or other documented thesis build wrapper exists. Generated LaTeX artifacts are ignored by Git.
+
+## Research-code prerequisites and configuration
+
+The code imports PyTorch, LMDB, python-dotenv, tqdm, and the non-repository `vsm_datascience_common` package, along with local modules under `code/`. Exact Python version and installable dependency set are not specified here; the SLURM launcher loads a site-specific Python 3.10 module, which is not a portable environment specification.
+
+Training needs writable locations for results, LMDB data, and logs. Unless a selected run configuration supplies those values, set these environment variables outside version control:
+
+- `RESULTS_ROOT_DIR`
+- `LMDB_ROOT_DIR`
+- `LOG_DIR`
+
+The scripts call `dotenv.load_dotenv()`, and `.env` is ignored. The required database access/configuration is implicit in `vsm_datascience_common`; this repository does not document how to obtain it.
+
+## Dataset creation
+
+> **Warning: data-sensitive operation.** Dataset creation queries the external cycle database and writes an LMDB dataset. Run it only with authorised data access and storage controls.
+
+`code/dataset_wrapper.py` accepts a model-configuration module, optional variable name, LMDB output directory, LMDB size, and worker count. Its command shape is:
+
+```sh
+cd code
+python dataset_wrapper.py --model_config_module <module> [--model_config_variable <variable>] [--lmdb_dir <directory>] [--lmdb_size <MB>] [--max_workers <count>]
+```
+
+The default model configuration variable is `model_configuration`. Confirm the selected configuration actually defines the variable and is compatible with the available data before running. The script filters cycles through the external database package, derives features, and writes/scales LMDB data.
+
+## Training and evaluation
+
+The current launcher generates a `torchrun` invocation locally or submits one with `sbatch`:
+
+```sh
+cd code
+python python_slurm_start.py local|slurm <run_config> [options]
+```
+
+Run configuration paths are relative to `code/` and identify a module and a run variable; for example, `configs/lstm_run.py` defines several named LSTM run configurations. The launcher supports `--num_gpus`, `--num_cpus_per_gpu`, `--item_limit`, and `--evaluate_only`; SLURM mode additionally requires a supported `--partition` and `--gpu_type`.
+
+> **Warning: site-specific batch operation.** SLURM mode hard-codes recognised partitions/GPU types, a log location, virtual-environment path, and module version. It submits work with `sbatch`; review and adapt it for an authorised cluster rather than assuming it is portable.
+
+A legacy `code/slurm_start.sh` also submits an `sbatch` script with seven positional arguments. It likewise contains site-specific assumptions and is not a general deployment interface.
+
+No command in this repository installs dependencies, provisions data, or runs automated tests. Validate runs first with authorised, non-sensitive resources and inspect generated logs/results in the configured directories.