Update model card

README.md

@@ -16,185 +16,161 @@ tags:
 # afMLevel-background-unet
 
 This U‑Net model predicts tilt, scanner drift, and other large‑scale imaging artifacts present in Atomic Force Microscopy (AFM) height maps.
-It outputs a **background** image, the same size and scale as the raw AFM image, which can be subtracted (via the accompanying [afMLevel](https://github.com/mayatek1/afMLevel) 
+It outputs a **background** image, the same size and scale as the raw AFM image, which can be subtracted (via the accompanying [afMLevel](https://github.com/mayatek1/afMLevel)
 code) to produce a levelled height map.
 
 ## Model Details
 
+This model is part of the [afMLevel](https://github.com/mayatek1/afMLevel) project.
+
 ### Model Description
 
-This model is part of the [afMLevel](https://github.com/mayatek1/afMLevel) project.
-The repository includes tools for:
+This model is a 7‑layer **U‑Net** architecture implemented in **PyTorch**, trained to perform image‑to‑image regression for background prediction in AFM height maps. The network was trained on **256 × 256‑pixel images** and therefore expects inputs of this size at inference time.
+
+The afMLevel repository includes tools for:
 
 - running inference,
 - subtracting the predicted background,
-- integrating the model into analysis workflows.
-
-The model is a 7‑layer **U‑Net**, adapted from the original U‑Net architecture, and implemented fully in **PyTorch**. 
-It performs image‑to‑image regression to estimate background height 'image' caused by physical and instrumental AFM artifacts.
-
+- integrating the model into AFM anasis workflows.
 
 - **Developed by:** Maya Tekchandani
-- **Maintained by:** Dr Daniel E. Rollins  
+- **Maintained by:** Dr Daniel E. Rollins
 - **Principal Investigator:** Dr George R. Heath
-- **Affiliation:** University of Leeds  
+- **Affiliation:** University of Leeds
 - **Funded by [optional]:** [More Information Needed]
-- **Shared by:** [Heath-AFM-Lab](https://heath-afm-lab.github.io/)
-- **Model type:** U‑Net regression model for AFM background prediction
+- **Shared by:** [Heath-AFMab](https://heath-afm-lab.github.io/)
+- **Model type:** U‑Net regression model for AFM background estimation
 - **License:** BSD‑3‑Clause
-- **Finetuned from model [optional]:** None (trained from scratch)
-
-### Model Sources [optional]
+- **Finetuned from model:** None (trained from scratch)
 
-<!-- Provide the basic links for the model. -->
+### Model Sources
 
 - **Repository:** https://github.com/mayatek1/afMLevel
-- **Paper [optional]:** In preparation
-- **Demo [optional]:** [Demonstration notebooks](https://github.com/mayatek1/afMLevel/tree/main/notebooks)
+- **Paper:** In preparation
+- **Demo notebooks:** https://github.com/mayatek1/afMLevel/tree/main/notebooks
 
-# Uses
+## Uses
 
-## Direct Use
+This model is designed for used within the [afMLevel](https://github.com/mayatek1/afMLevel/) `background_model` module.
 
-The [afMLevel](https://github.com/mayatek1/afMLevel/) inference code operates on **NumPy arrays**, so raw AFM files must first be 
-loaded using an external reader such as [playnano](https://github.com/derollins/playNano), [AFMReader](https://github.com/AFM-SPM/AFMReader), or a custom 
-loader. Once loaded, the afMLevel repo and notebooks handle inference and output of either 
-the predicted background or the levelled image directly.
+### Direct Use
 
-The model has been primarily tested on **biological AFM data** and is best suited to that 
-context, though it may generalise to other sample types with similar imaging characteristics.
+The [afMLevel](https://github.com/mayatek1/afMLevel/) model aplication package operates on **NumPy arrays**, so raw AFM files must first be loaded using an external reader such as [playnano](https://github.com/derollins/playNano), [AFMReader](https://github.com/AFM-SPM/AFMReader), or a custom loader. Once loaded, afMLevel handles inference and outputs either the predicted background or the final levelled image.
 
-## Downstream Use
+The model has been primarily tested on **biological AFM data**. It may generalise to other sample types with similar imaging characteristics.
 
-- Integration into the **playNano** package, which also handles file reading, making it a 
-natural end-to-end workflow.
-- Batch levelling of **high-speed AFM videos** via playnano.
-- As a preprocessing step feeding into segmentation, particle detection, or other analysis 
-tools.
+### Downstream Use
 
-## Out‑of‑Scope Use
+- Integration into **playNano**, enabling end‑to‑end reading and levelling.
+- Batch levelling of **high‑speed AFM videos** via playNano.
+- Preprocessing for segmentation, particle detection, or other AFM analysis tools.
+
+### Out‑of‑Scope Use
 
 This model is **not** intended for:
 
-- predicting physical or mechanical properties of samples,
-- denoising extremely corrupted AFM images outside the training distribution,
-- interpreting AFM contact mechanics,
-- working on specialized AFM modes (KPFM, MFM, FMM, etc.) without validation,
-- non-biological samples, without first validating performance on representative images.
+- prediction of physical or mechanical properties,
+- denoising heavily corrupted AFM scans outside the training distrution,
+- interpretation of AFM contact mechanics,
+- specialised AFM modes (KPFM, MFM, FMM, etc.) without validation,
+- non‑biological samples without performance verification.
 
-# Bias, Risks, and Limitations
+## Bias, Risks, and Limitations
 
-- The model was trained on a specific dataset of real AFM height maps; performance may degrade for very different imaging modes, scan sizes, or materials.  
-- Extremely noisy scans or those containing jump‑to‑contact instabilities may produce inaccurate background predictions.  
+- The model was trained on a specific dataset of real AFM height maps; performance may degrade for very different imaging modes, scan sizes, or materials.
+- Extremely noisy scans or those containing jump‑to‑contact instabilities may produce inaccurate background predictions.
 - Users should visually inspect levelled outputs before scientific interpretation.
 
 ### Recommendations
 
-- Always verify a subset of corrected images manually.  
-- Avoid applying the model to AFM imaging modes it has not been trained on (i.e. phase, electrical, magnetic modes).
+- Manually verify a subset of levelled images.
+- Avoid applying the model to imaging modes it was not trained on.
 
 ## How to Get Started with the Model
 
-The recommended way to use this model is through the 
-[afMLevel](https://github.com/mayatek1/afMLevel) repository, which handles inference, 
-background subtraction, and output. Demonstration notebooks are available 
-[here](https://github.com/mayatek1/afMLevel/tree/main/notebooks).
+Use the model through the [afMLevel](https://github.com/mayatek1/afMLevel) repository, which handles background prediction, subtraction, and output generation. Demonstration notebooks are provided in the repository.
 
 ## Training Details
 
-The model was trained from scratch on real AFM topography data using the PyTorch framework.
+The model was trained from scratch on real AFM topography data using PyTorch.
 
 ### Training Data
 
-This model was trained on a **non‑public dataset of 2,001 real AFM height‑map images**.  
+This model was trained on a **non‑public dataset of 2,001 real AFM height‑map images**.
 To increase dataset size and improve generalization, images were augmented using:
 
-- reflection along the y-axis,
-- rotation by 180°,
-- (mask model only) synthetic line-noise artefacts.
+- reflection along the y‑axis,
+- rotation by 180°.
 
-This produced **6,003 training images** for the background model.  
+This produced **6,003 training images**.
 A **60:40 train‑validation split** was used.
 
 ### Training Procedure
 
-- **Architecture:** 7‑layer U‑Net with large convolutional filters (9×9)  
-- **Framework:** PyTorch  
-- **Optimizer:** Adam  
-- **Learning rate:** 0.0005  
-- **Objective:** pixel‑wise continuous regression to target background images  
-- **Hardware:** trained using GPU acceleration  
-- Loss‑curve diagnostics were used to monitor convergence.
+- **Architecture:** 7‑layer U‑Net with large convolutional filters (9×9)
+- **Framework:** PyTorch
+- **Optimizer:** Adam
+- **Learning rate:** 0.0005
+- **Objective:** pixel‑wise continuous regression
+- **Hardware:** trained with GPU acceleration
+- Loss curves were monitored to assess convergence.
 
-#### Preprocessing [optional]
+#### Preprocessing
 
 [More Information Needed]
 
-
 #### Training Hyperparameters
 
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
-
-#### Speeds, Sizes, Times [optional]
+- **Training regime:** [More Information Needed]
 
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
+#### Speeds, Sizes, Times
 
 [More Information Needed]
 
 ## Evaluation
 
-<!-- This section describes the evaluation protocols and provides the results. -->
+The performance of the background model was evaluated indirectly through its impact on automated levelling. The main metric used was **Mean Squared Error (MSE)** between the auto‑levelled output and manually levelled ground‑truth images. Visual inspection was also carried out by the developers. Full evaluation results will be provided in the accompanying paper (in preparation).
 
-### Testing Data, Factors & Metrics
+### Testing Data
 
-#### Testing Data
+Evaluation was performed on a held‑out set of real AFM height maps spanning a wide range of:
 
-<!-- This should link to a Dataset Card if possible. -->
+- biological sale types,
+- imaging conditions,
+- noise levels,
+- numbers of surface planes,
+- scan artefacts (e.g., streaks, line noise).
 
-[More Information Needed]
-
-#### Factors
+*A dataset link will be added when appropriate.*
 
-<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
+### Metrics
 
-[More Information Needed]
-
-#### Metrics
-
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
-
-[More Information Needed]
+- **Primary metric:** MSE between auto‑levelled and manually levelled images
+- **Distribution analysis:** comparing mean vs median MSE
+- **Success‑rate metric:** proportion of images with MSE < 0.1 (empirical “well‑levelled” threshold)
 
 ### Results
 
-[More Information Needed]
-
-#### Summary
+Initial internal testing indicates that the background model supports reliable automated levelling across a broad range of AFM images. Full quantitative and statistical analyses will be included in the companion paper (in preparation).
 
+## Citation
 
-
-## Citation [optional]
-
-Paper in preparation
+Paper in praration
 
 **BibTeX:**
-
-[More Information Needed]
+[More Inrmation Needed]
 
 **APA:**
-
 [More Information Needed]
 
-## Model Card Authors [optional]
-
-- **Maya Tekchandani** (primary developer) 
-- **Dr Daniel E. Rollins** (maintainer)   
-- **Dr George R. Heath** (project supervisor & PI)
+## Model Card Authors
 
-## Model Card Contact
+- **Maya Tekchandani**
+- **Dr Daniel E. Rollins**
+- **Dr George R. Heath**
 
-# Contact
+## Contact
 
-For questions or issues, please contact:  
-**George R. Heath- University of Leeds**  
+For questions or issues, please contact:
+**George R. Heath, University of Leeds**
 Email: G.R.Heath@leeds.ac.uk