74 lines
4.8 KiB
Markdown
74 lines
4.8 KiB
Markdown
# 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.
|