Contributing to PROTÉGÉ PD

**Description:**
Clear, concise description of the issue

**Steps to Reproduce:**
1. Run command: `docker run ... protege-pd -s sequences.fna`
2. Observe error at alignment step
3. ...

**Expected Behavior:**
What should happen

**Actual Behavior:**
What actually happens

**Environment:**
- OS: Ubuntu 22.04 / macOS 13 / Windows 11
- Docker version: 24.0.5
- PROTÉGÉ PD version: v1.0.2
- Number of sequences: 150
- Average sequence length: 1200 bp

**Error Messages:**
```text
Paste error messages or logs here
```text

**Additional Context:**
Any other relevant information
```text

<Accordion title="Example: Good Bug Report">
  **Title:** MUSCLE alignment fails with >500 sequences

  **Description:**
  When processing datasets with more than 500 sequences, the MUSCLE alignment step crashes with a memory error.

  **Steps to Reproduce:**
  1. Prepare FASTA file with 550 sequences (avg length 1500 bp)
  2. Run: `docker run --rm --mount type=bind,source=$(pwd),target=/root/. --name protege -p 127.0.0.1:8050:8050 --cpus 4 ddelgadillo/protege_base:v1.0.2 protege-pd -s large_dataset.fna`
  3. Wait for alignment step

  **Expected:** Alignment completes successfully  
  **Actual:** Container crashes with "Killed" message

  **Environment:**
  - OS: Ubuntu 22.04
  - Docker: 24.0.5 (8GB RAM allocated)
  - PROTÉGÉ: v1.0.2
  - Dataset: 550 sequences, 1500 bp average

  **Logs:**
  ```text
  Alignment length 520
  Killed
  ```text
</Accordion>

### Suggesting Features

Propose new features or enhancements to existing functionality.

**Feature request template:**

```text
**Feature Description:**
What functionality would you like to see?

**Use Case:**
Why is this feature valuable? What problem does it solve?

**Proposed Implementation:**
(Optional) How might this be implemented?

**Alternatives Considered:**
What other solutions have you considered?

**Priority:**
How critical is this feature for your workflow?
```text

<Note>
  Feature requests should align with PROTÉGÉ PD's core mission: phylogenetic primer design for protein-coding genes.
</Note>

### Improving Documentation

Documentation improvements are highly valuable:

- Fix typos or unclear explanations
- Add examples for common use cases
- Improve installation instructions
- Add troubleshooting tips
- Translate documentation (if applicable)

**To contribute documentation:**
1. Fork the repository
2. Edit README.md or create new documentation files
3. Submit a pull request with clear description of changes

## Development Setup

### Prerequisites

**Required software:**
- Python 3.10+
- Git
- Docker (for testing containerized version)
- Text editor or IDE (VSCode, PyCharm, etc.)

**Optional tools:**
- `black` for code formatting
- `pylint` for linting
- `pytest` for testing

### Clone the Repository

```bash
git clone https://github.com/ddelgadillod/ProtegePD.git
cd ProtegePD

chmod +x muscle/muscle_lin  # Linux
# Or download appropriate version for your OS

pip3 install -r requirements.txt

# Make scripts executable
chmod +x protege.py phl.py

# Run with test data
./protege.py -s test_files/test.fasta

# Or use Python directly
python3 protege.py -s test_files/test.fasta

# Small test dataset
python3 protege.py -s test_files/test.fasta

# Medium dataset (gyrB gene)
python3 protege.py -s test_files/gyrB_genes.fas -c 90 -d 7

# Aligned sequences
python3 protege.py -s test_files/aligned_by_codons.fas

ProtegePD/
├── protege.py          # Main application
├── phl.py              # Primer analysis module
├── Dockerfile          # Container configuration
├── requirements.txt    # Python dependencies
├── install.sh          # Local installation script
├── README.md           # Project documentation
├── assets/             # Web interface assets (CSS, images)
├── muscle/
│   └── muscle_lin      # MUSCLE alignment binary (Linux)
├── src/                # Source code (alternative location)
│   ├── main.py
│   ├── protege.py
│   └── phl.py
└── test_files/         # Test datasets
    ├── test.fasta
    ├── gyrB_genes.fas
    ├── aligned_by_codons.fas
    └── *.fas (various test cases)
```text

### Algorithm Overview

**Primer design workflow:**

1. **Sequence Input** (`protege.py:132-144`)
   - Read FASTA file
   - Translate nucleotide sequences to amino acids
   - Store both nucleotide and amino acid sequences

2. **Multiple Sequence Alignment** (`protege.py:179-183`)
   - Align amino acid sequences using MUSCLE
   - Command: `muscle_lin -in translated.fas -out aligned.fas`

3. **Back-translation** (`protege.py:207-235`)
   - Map amino acid alignment to nucleotide codons
   - Preserve alignment gaps in nucleotide sequences

4. **Consensus Calculation** (`protege.py:246-300`)
   - Calculate nucleotide frequency at each position
   - Apply consensus threshold (default 90%)
   - Generate IUPAC degeneracy codes for ambiguous positions

5. **Primer Candidate Generation** (`protege.py:305-323`)
   - Slide window across consensus (default 21 bp = 7 codons)
   - Calculate degeneracy for each candidate
   - Filter candidates with gaps

6. **Melting Temperature Analysis** (`phl.py:162-193`)
   - Four calculation methods: Wallace, GC-based, Bio.SeqUtils
   - Generate distribution for all primer combinations

7. **Interactive Visualization** (`protege.py:437-577`)
   - Dash web interface on port 8050
   - Plotly scatter plots for primer selection
   - Real-time Tm distribution updates

## Making Code Contributions

### Development Workflow

1. **Fork the repository**
   - Visit https://github.com/ddelgadillod/ProtegePD
   - Click "Fork" button (top right)

2. **Create a feature branch**
   ```bash
   git checkout -b feature/your-feature-name
   # or
   git checkout -b bugfix/issue-description

## Description
Clear description of what this PR does

## Changes
- List of specific changes made
- Modified files and why

## Testing
- What tests were performed
- Test datasets used
- Expected vs actual results

## Related Issues
Fixes #123 (if applicable)

## Checklist
- [ ] Code follows existing style
- [ ] Comments added for complex logic
- [ ] Tested with multiple datasets
- [ ] Documentation updated (if needed)
- [ ] No breaking changes (or documented if necessary)
```text

<Warning>
  **Breaking changes** (changes that break backward compatibility) should be clearly documented and discussed with maintainers before implementation.
</Warning>

### Code Style Guidelines

**Python style:**
- Follow PEP 8 conventions
- Use descriptive variable names
- Add docstrings to functions and classes
- Keep functions focused (single responsibility)

**Example:**

```python
# Good
def calculate_consensus_position(nucleotide_list, threshold=90, allow_gaps=True):
    """
    Calculate consensus nucleotide at a specific alignment position.
    
    Args:
        nucleotide_list: List of nucleotides at this position
        threshold: Minimum percentage for consensus (default 90)
        allow_gaps: Whether to consider gaps in consensus (default True)
    
    Returns:
        str: Consensus nucleotide or IUPAC degeneracy code
    """
    # Implementation...
    pass

# Avoid
def calc(nl, t=90, g=True):
    # Implementation without documentation
    pass

# Good
# Use Wallace's rule of thumb: Tm = 4(G+C) + 2(A+T)
# More accurate for primers 14-20 bp (Rychlik, 1990)
temp = 4 * gc_count + 2 * at_count

# Less helpful
# Calculate temperature
temp = 4 * gc_count + 2 * at_count

# Small dataset (quick test)
python3 protege.py -s test_files/test.fasta

# Verify outputs created:
ls -la sequences.csv alSequences.csv protege_consensus.csv

# Check web interface:
# Open browser to http://127.0.0.1:8050
# Verify plots render correctly

# Lower consensus threshold
python3 protege.py -s test_files/test.fasta -c 80

# Different codon length
python3 protege.py -s test_files/test.fasta -d 6

# Disable gap consensus
python3 protege.py -s test_files/test.fasta -g

# Verbose output
python3 protege.py -s test_files/test.fasta -v

# Build local image
docker build -t protege-test:latest .

# Run with test data
cd test_files
docker run --rm \
  --mount type=bind,source=$(pwd),target=/root/. \
  --name protege-test -p 127.0.0.1:8050:8050 --cpus 4 \
  protege-test:latest \
  protege-pd -s test.fasta

# Verify container behavior
docker logs protege-test
docker stats protege-test