docs: refresh README

README.md

@@ -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.

thesis/sections/appendix.tex

@@ -21,7 +21,7 @@ and after-OV (0.0833) all occurring at 20 days.
 The \textbf{Convolutional Transformer} performs best overall at 40 days and best before ovulation at 160 days (MSE 0.0286).
 See Table~\ref{tab:ovover_windows_compact_mse} for a summary.
 
-\begin{table}[t]
+\begin{table}[htbp]
     \small
     \renewcommand{\arraystretch}{1.15}
     \setlength{\tabcolsep}{6pt}
@@ -68,7 +68,7 @@ with lowest before-OV MSE at 12/day (0.0255) and after-OV MSE at 288/day (0.0578
 Results are summarized in Table~\ref{tab:ovover_resolution_compact_mse};
 full resolution grids are in Appendix Table~\ref{tab:ov_over_results_by_resolution}.
 
-\begin{table}[t]
+\begin{table}[htbp]
     \small
     \renewcommand{\arraystretch}{1.15}
     \setlength{\tabcolsep}{6pt}
@@ -110,7 +110,7 @@ Finally, the \textbf{Convolutional Transformer} achieves its lowest overall and
 Table~\ref{tab:ovover_params_compact_mse} summarizes these parameter-dependent results;
 full comparisons are included in Appendix Tables~\ref{tab:ov_over_results_by_model_parameters_lstm}–\ref{tab:ov_over_results_by_model_parameters_conv_transformer}.
 
-\begin{table}[t]
+\begin{table}[htbp]
     \scriptsize
     \renewcommand{\arraystretch}{1.15}
     \setlength{\tabcolsep}{6pt}
@@ -198,7 +198,7 @@ As before, all learned models outperform the baselines by a wide margin.
 The full table with MSE and MAE for all models can be found in the appendix, Table~\ref{tab:regular_vs_irregular_ov_over_results}.
 
 
-\section{Extra Figures}\label{app:figs}
+\section{Extra Tables}\label{app:tabs}
 
 \begin{landscape}
     \begin{table}

thesis/sections/background.tex

@@ -593,7 +593,7 @@ In practice, convolutional architectures have achieved strong performance on seq
 For example,~\citeauthor{lecun_convolutional_1998} showed that a simple Temporal Convolutional Network often outperforms canonical
 recurrent models (like LSTMs) across diverse sequence modeling benchmarks.
 Their experiments suggest that CNNs are “a natural starting point for sequence modeling,”
-especially when temporal features are local or multi-scale.
+especially when temporal features are local or multiscale.
 In summary, 1D convolutions provide an efficient way to extract local temporal features and compress high-resolution sequences,
 complementing recurrent and attention-based models in time-series analysis
 

thesis/sections/introduction.tex

@@ -12,7 +12,7 @@ At the same time, many individuals seek alternatives to hormonal contraception,
 Accurate fertility prediction thus carries implications not only for individual reproductive autonomy,
 but also for public health, demographic trends, and the development of safe, data-driven fertility support tools.
 
-While textbooks often describe a menstrual cycle as lasting 28 to 30 days with ovulation around day 14~\cite{owen_physiology_nodate},
+While textbooks often describe a menstrual cycle as lasting 28 to 30 days with ovulation around day 14~\cite{owen_physiology_1975},
 such regularity is the exception rather than the rule~\cite{munster_length_1992, bull_real-world_2019}.
 For individuals with consistent cycle patterns, simple calendar-based predictions may suffice.
 However, for the majority, especially with increasing age and associated irregularity, more sophisticated methods are necessary.

thesis/sections/methodology.tex

@@ -286,8 +286,8 @@ Then each input token at time \( t \in \{1, \dots, T\} \) is:
 The full input sequence is then represented as a matrix:
 \[
     X = \begin{bmatrix}
-            x_1 \\
-            x_2 \\
+            x_1    \\
+            x_2    \\
             \vdots \\
             x_T
     \end{bmatrix}
@@ -525,11 +525,11 @@ and whether incorporating data from previous cycles improves learning or introdu
         Window length      & Historical context in days (input window size) & 10, 20, 40, 80, 160          \\
         \bottomrule
     \end{tabular}
-    \caption{Input-related hyperparameters for LSTM and Transformer models.}
+    \caption{\parbox{\linewidth}{Input-related hyperparameters for LSTM and Transformer models.}}
     \label{tab:input_hyperparameters_basic}
 \end{table}
 
-\begin{table}[ht]
+\begin{table}[htbp]
     \centering
     \begin{tabular}{l>{\raggedright\arraybackslash}p{0.45\linewidth}>{\raggedright\arraybackslash}p{0.3\linewidth}}
         \toprule
@@ -897,4 +897,12 @@ Explicit fairness evaluations and diverse validation cohorts are essential befor
 work is a medical device company, which underscores the need to guard against commercial bias.
 Results should be independently validated, and any translation into clinical or consumer use must be preceded by prospective,
 peer-reviewed trials.
-Without such validation, deploying fertility prediction tools risks undermining trust and causing harm. \\
+Without such validation, deploying fertility prediction tools risks undermining trust and causing harm.
+
+
+\section{Code Availability}\label{sec:code_availability}
+The complete source code and LaTeX files used for this thesis are available at:\\
+\small
+\url{https://gitlab.com/blankinator/temperature-based-fertility-prediction-thesis}\\
+\normalsize
+The repository is archived under the release v1.1-thesis-final.

thesis/sections/results.tex

@@ -45,7 +45,7 @@ The \textbf{Convolutional Transformer} achieves the lowest overall MSE (0.0041)
 A summary of best-performing window lengths per architecture is shown in Table~\ref{tab:fertility_windows_compact_mse};
 full results including MAE are provided in Appendix Table~\ref{tab:fertility_results_by_window_length}.
 
-\begin{table}[t]
+\begin{table}[htbp]
     \small
     \renewcommand{\arraystretch}{1.15}
     \setlength{\tabcolsep}{6pt}
@@ -100,7 +100,7 @@ though higher resolutions can be advantageous for detecting short-term fertile-d
 Results are summarized in Table~\ref{tab:fertility_resolution_compact_mse}; full metrics are in Appendix Table~\ref{tab:fertility_results_by_window_resolution}.
 
 
-\begin{table}[t]
+\begin{table}[htbp]
     \small
     \renewcommand{\arraystretch}{1.15}
     \setlength{\tabcolsep}{6pt}
@@ -148,7 +148,7 @@ Detailed comparisons are shown in Table~\ref{tab:fertility_params_compact_mse},
 with full results in Appendix Tables~\ref{tab:fertility_results_by_model_parameters_lstm}–\ref{tab:fertility_results_by_model_parameters_conv_transformer}.
 
 
-\begin{table}[t]
+\begin{table}[htbp]
     \scriptsize
     \renewcommand{\arraystretch}{1.15}
     \setlength{\tabcolsep}{6pt}