Update README.md

README.md

@@ -1,3 +1,200 @@
----
-license: bsd-3-clause
----
+---
+license: bsd-3-clause
+pipeline_tag: image-to-image
+tags:
+- AFM
+- physics
+- biology
+- atomic-force-microscopy
+- microscopy
+- image-processing
+- unet
+- surface-analysis
+- chemistry
+- nanoscience
+---
+# 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) 
+code) to produce a levelled height map.
+
+## Model Details
+
+### Model Description
+
+This model is part of the [afMLevel](https://github.com/mayatek1/afMLevel) project.
+The 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.
+
+
+- **Developed by:** Maya Tekchandani
+- **Maintained by:** Dr Daniel E. Rollins  
+- **Principal Investigator:** Dr George R. Heath
+- **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
+- **License:** BSD‑3‑Clause
+- **Finetuned from model [optional]:** None (trained from scratch)
+
+### Model Sources [optional]
+
+<!-- Provide the basic links for the model. -->
+
+- **Repository:** https://github.com/mayatek1/afMLevel
+- **Paper [optional]:** In preparation
+- **Demo [optional]:** [Demonstration notebooks](https://github.com/mayatek1/afMLevel/tree/main/notebooks)
+
+# Uses
+
+## Direct Use
+
+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.
+
+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.
+
+## Downstream Use
+
+- 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.
+
+## 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.
+
+# 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.  
+- 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).
+
+## 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).
+
+## Training Details
+
+The model was trained from scratch on real AFM topography data using the PyTorch framework.
+
+### Training Data
+
+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.
+
+This produced **6,003 training images** for the background model.  
+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.
+
+#### Preprocessing [optional]
+
+[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]
+
+<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
+
+[More Information Needed]
+
+## Evaluation
+
+<!-- This section describes the evaluation protocols and provides the results. -->
+
+### Testing Data, Factors & Metrics
+
+#### Testing Data
+
+<!-- This should link to a Dataset Card if possible. -->
+
+[More Information Needed]
+
+#### Factors
+
+<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
+
+[More Information Needed]
+
+#### Metrics
+
+<!-- These are the evaluation metrics being used, ideally with a description of why. -->
+
+[More Information Needed]
+
+### Results
+
+[More Information Needed]
+
+#### Summary
+
+
+
+## Citation [optional]
+
+Paper in preparation
+
+**BibTeX:**
+
+[More Information 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 Contact
+
+# Contact
+
+For questions or issues, please contact:  
+**George R. Heath- University of Leeds**  
+Email: G.R.Heath@leeds.ac.uk