Installation

Prerequisites

Python 3.8 or higher
PyTorch 2.4.0 or higher
CUDA-capable GPU (optional, for faster training)
Git (for cloning the repository)

Installing uv Package Manager

uv is a fast Python package installer and resolver. Install it using:

# Install uv using curl (Linux/macOS)
curl -LsSf https://astral.sh/uv/install.sh | sh

You should see output similar to:

downloading uv 0.11.2 x86_64-unknown-linux-gnu
installing to /home/username/.local/bin
  uv
  uvx
everything's installed!

Add uv to your PATH

To use uv from anywhere, add it to your shell configuration:

# Add to ~/.bashrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

# Reload your shell configuration
source ~/.bashrc

Verify the installation:

uv --version
which uv

You should see:

uv 0.11.2
/home/username/.local/bin/uv

Installing PhenoNN

Clone the repository:

git clone https://github.com/kardaneh/PhenoNN.git
cd PhenoNN

Create a virtual environment:
```
uv venv --python 3.8 # or 3.9, 3.10, 3.11, 3.12
```
This creates a virtual environment in the .venv directory.
Activate the virtual environment:
```
# Linux/macOS
source .venv/bin/activate
```
You should see (PhenoNN) appear at the beginning of your terminal prompt.
Install PhenoNN with all dependencies:

For basic installation:
```
uv pip install -e .
```
For installation with documentation dependencies (for building docs):
```
uv pip install -e ".[docs]"
```
For installation with development dependencies (testing, formatting):
```
uv pip install -e ".[dev]"
```
To install all extras:
```
uv pip install -e ".[ci,docs,dev]"
```

Verification

Verify the installation by running:

# Check Python version
python --version

# Check PhenoNN installation
python  tests/test_phenonn_installation.py
# Should print "SUCCESS! PhenoNN is fully installed and ready to use!"

# Check CLI
phenonn --help

# Check PyTorch installation
python -c "import torch; print(f'PyTorch {torch.__version__}')"

You should see output similar to:

Python 3.10.12
0.1.0
usage: phenonn [-h] [--version] {predict,train,hp-tuning} ...
PyTorch 2.4.1

Dependencies

PhenoNN automatically installs the following main dependencies:

PyTorch >= 2.4.0: Deep learning framework
NumPy >= 1.20.0: Numerical computing
Pandas >= 2.0.3: Data manipulation
Matplotlib >= 3.3.0: Plotting and visualization
Scikit-learn >= 1.3.2: Machine learning metrics
SciPy >= 1.10.1: Scientific computing
TQDM >= 4.65.1: Progress bars
Xarray >= 2023.1.0: Labeled multi-dimensional arrays
NetCDF4 >= 1.7.2: NetCDF file support
Seaborn >= 0.13.2: Statistical data visualization

Optional Dependencies

If you installed with extras:

docs: Sphinx and related packages for building documentation
dev: Development tools (pre-commit, ruff, pytest)

Troubleshooting

If you encounter issues:

1. ModuleNotFoundError

Ensure your virtual environment is activated:

source .venv/bin/activate

2. PyTorch installation issues

Install PyTorch separately:

uv pip uninstall torch
uv pip install torch --index-url https://download.pytorch.org/whl/cpu

3. Permission errors

Use –user flag or ensure proper permissions:

uv pip install --user -e .

4. Python version issues

PhenoNN requires Python 3.8+. Check your version:

python --version

For more help, visit the GitHub repository: https://github.com/kardaneh/PhenoNN