temperature-based-fertility-prediction-thesis/README.md

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:

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:

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:

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.