Update README.md

README.md

@@ -1,11 +1,146 @@
 ---
-library_name: FoldVision
+license: mit
+library_name: pytorch
 pipeline_tag: feature-extraction
 tags:
-- model_hub_mixin
-- pytorch_model_hub_mixin
+  - protein
+  - structural-biology
+  - representation-learning
+  - 3d-cnn
+  - foldvision
 ---
 
-This model has been pushed to the Hub using the [PytorchModelHubMixin](https://huggingface.co/docs/huggingface_hub/package_reference/mixins#huggingface_hub.PyTorchModelHubMixin) integration:
-- Library: [More Information Needed]
-- Docs: [More Information Needed]
+# FoldVision Encoder
+
+## Model Summary
+
+FoldVision is a protein 3D-CNN encoder that maps a voxelized protein structure to a fixed-size embedding (`1024` dimensions).
+
+Primary task:
+- **Protein feature extraction** from 3D structure.
+
+Typical downstream tasks (with finetuning heads):
+- Protein-only regression/classification.
+- PSI (**protein-small molecule interactions**) prediction when combined with a SMILES encoder.
+
+GitHub code: [foldvision_github](https://github.com/<YOUR_ORG_OR_USER>/foldvision_github)
+
+## Model Details
+
+- Model name: `AlexanderKroll/foldvision-encoder`
+- Architecture: 3D CNN encoder with GroupNorm blocks and global pooling.
+- Framework: PyTorch
+- Input channels: 5 atom-type channels (`C`, `N`, `S`, `O`, `P`)
+- Output: `(B, 1024)` embedding
+
+## Intended Use
+
+Use this model to compute protein structure embeddings for:
+- similarity and retrieval workflows,
+- downstream supervised tasks (classification/regression),
+- multimodal PSI pipelines with a molecule language model.
+
+## Out-of-Scope Use
+
+- Clinical decision making.
+- Any safety-critical use without task-specific validation.
+- Interpretation as direct biochemical or medical truth without experimental verification.
+
+## Input and Preprocessing
+
+This model expects FoldVision voxel tensors generated from PDB structures.
+
+Recommended preprocessing pipeline:
+1. Convert `.pdb` files to sparse point lists (`numpy_3D_point_lists/*.npz`).
+2. Use `bounding_boxes.npy` + dataloader to construct dense tensors at runtime.
+
+Repository scripts:
+- `scripts/preprocess_pdb_dir.py`
+- `scripts/embed_proteins.py`
+- `scripts/train.py`
+- `scripts/train_PSI.py`
+- `scripts/evaluate.py`
+- `scripts/evaluate_PSI.py`
+
+## Usage
+
+```python
+from foldvision import FoldVisionEncoder
+
+model = FoldVisionEncoder.from_pretrained("AlexanderKroll/foldvision-encoder")
+model.eval()
+# x: (B, 5, Z, Y, X)
+# z = model(x)  # (B, 1024)
+```
+
+## Multi-Run Embeddings and Predictions
+
+FoldVision pipelines support repeated runs with random 3D rotations (test-time augmentation).
+
+- Embeddings:
+  - per-run: keep each run-specific embedding,
+  - aggregated: use mean embedding for a stable representation.
+- Predictions:
+  - per-run predictions can be used to inspect spread/uncertainty,
+  - averaged predictions are recommended for reporting.
+
+## Training and Evaluation Data
+
+Please document here the exact datasets used for pretraining and downstream evaluation.
+
+Example datasets referenced in this repository:
+- PTEN activity
+- SPOT
+- Davis
+- small dummy data files for smoke tests (not representative for benchmarking)
+
+## Metrics
+
+Report the official metrics from your manuscript for your release version.
+
+Suggested metrics by task:
+- Regression: Spearman, Pearson, MAE, RMSE, R2
+- Binary: Accuracy, MCC, ROC-AUC
+
+## Limitations
+
+- Performance depends strongly on preprocessing consistency.
+- Rotational augmentation can change single-run outputs; use multi-run means for stability.
+- Generalization to new protein families/domains must be validated per task.
+
+## Risks and Biases
+
+- Dataset composition can bias performance across protein classes.
+- Downstream labels and splits can introduce benchmark-specific bias.
+
+## Citation
+
+If you use this model, cite:
+
+1. **FoldVision bioRxiv manuscript**:
+
+```bibtex
+@article{foldvision_biorxiv,
+  title   = {FoldVision: A compute-efficient atom-level 3D protein encoder},
+  author  = {Kroll, Alexander and Yadav, Shantanu and Lercher, Martin J.},
+  journal = {bioRxiv},
+  year    = {2026},
+  doi     = {10.64898/2026.01.23.701326},
+  url     = {https://doi.org/10.64898/2026.01.23.701326}
+}
+```
+
+2. The GitHub repository:
+
+```bibtex
+@misc{foldvision_github,
+  title        = {FoldVision code repository},
+  author       = {Kroll, Alexander},
+  year         = {2026},
+  howpublished = {\url{https://github.com/AlexanderKroll/foldvision}}
+}
+```
+
+## Model Card Contact
+
+For issues or questions, use the GitHub issue tracker in the FoldVision repository.