Metadata-Version: 2.4
Name: graphtfactor
Version: 0.1.2
Summary: GraphTFactor: Modeling Protein Sequences as Graphs for Accurate Transcription Factor Prediction
License: MIT License
        
        Copyright (c) 2026 Salvatore Calderaro
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/salvatorecalderaro/GraphTFactor
Project-URL: Repository, https://github.com/salvatorecalderaro/GraphTFactor
Project-URL: Issues, https://github.com/salvatorecalderaro/GraphTFactor/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fair-esm==2.0.0
Requires-Dist: numba<0.69,>=0.67.0
Requires-Dist: numpy<3,>=2.5.2
Requires-Dist: torch<3,>=2.8.0
Requires-Dist: torch-geometric<3,>=2.8.0.post1
Requires-Dist: tqdm<5,>=4.67.1
Dynamic: license-file

# GraphTFactor

<p align="center">
  <img src="https://raw.githubusercontent.com/salvatorecalderaro/GraphTFactor/main/images/logo.png" alt="GraphTFactor logo" width="280">
</p>

GraphTFactor predicts whether a protein is a transcription factor using protein language model embeddings and a graph neural network. It segments protein sequences with a minimum description length method, builds a graph from the segments, and predicts a class for each sequence.

## Install

```bash
python -m pip install graphtfactor
```

Python 3.10 or newer is required. The package includes the pretrained GraphTFactor classifier checkpoints for all supported organism groups and ESM layer configurations. The first time a configuration is used, `fair-esm` downloads the corresponding ESM-2 model weights; internet access is needed for that download. ESM-2 models range from 8 million to 15 billion parameters, so memory and accelerator requirements vary substantially. Start with 6 layers if you are unsure.

PyTorch supports CPU, NVIDIA CUDA, and Apple Silicon MPS, subject to the PyTorch build installed for your platform. For CUDA, install the matching PyTorch build using the instructions on the [official PyTorch site](https://pytorch.org/get-started/locally/) before installing GraphTFactor.

## Quick start

```python
import torch
from graphtfactor import GraphTFactor

if torch.cuda.is_available():
    device = "cuda"
elif torch.backends.mps.is_available():
    device = "mps"
else:
    device = "cpu"

model = GraphTFactor(device=device, esm_layers=6, org="Virus")
predictions, probabilities = model.predict([
    "MDQYITLVELYIYDCNLFKSKNLKSFYKVHRVPEGDIVPKRRGGQLAGVTKSWVETNLVH"
])

print(predictions)    # class: 0 (non-TF) or 1 (TF)
print(probabilities)  # probability for the predicted class
```

`predict()` takes a list of amino-acid sequences and returns two lists, one with predicted class labels and one with their predicted-class probabilities. Unrecognized amino-acid symbols are treated as `X`.

## Supported models

Choose `org` from `"All"`, `"Virus"`, `"Eukaryotic"`, or `"Prokaryotic"`. Choose `esm_layers` from `6`, `12`, `30`, `33`, `36`, or `48`.

| `esm_layers` | ESM-2 model | Parameters |
| ---: | --- | ---: |
| 6 | `esm2_t6_8M_UR50D` | 8M |
| 12 | `esm2_t12_35M_UR50D` | 35M |
| 30 | `esm2_t30_150M_UR50D` | 150M |
| 33 | `esm2_t33_650M_UR50D` | 650M |
| 36 | `esm2_t36_3B_UR50D` | 3B |
| 48 | `esm2_t48_15B_UR50D` | 15B |

Larger ESM-2 models require considerably more memory and may not run on every device.

## Streamlit app

Try the [GraphTFactor Streamlit app](https://graphtfactor.streamlit.app/). Paste a protein sequence, select an ESM-2 model and organism group, and view the predicted class, confidence, and protein graph.

![Screenshot of the GraphTFactor Streamlit app](https://raw.githubusercontent.com/salvatorecalderaro/GraphTFactor/main/images/webappp_demo.png)

The app source and research experiments are available in the [GitHub repository](https://github.com/salvatorecalderaro/GraphTFactor).

## Citation

A paper citation will be added here when the publication details are available.

## License

GraphTFactor is distributed under the MIT License. See [LICENSE](LICENSE).

## Contact

For questions, feedback, or collaboration inquiries, email [Salvatore Calderaro](mailto:salvatore.calderaro01@unipa.it) or open an issue in the [GitHub repository](https://github.com/salvatorecalderaro/GraphTFactor/issues).
