pedigree-draw/README.md

# Pedigree Draw

A professional pedigree (family tree) drawing tool for genetic counselors and bioinformatics professionals.

## Features

- Import/Export GATK PED files
- Interactive web-based editor
- Support for standard pedigree symbols (NSGC standards)
- Export to SVG, PNG, or PED format
- Full pedigree features: affected/unaffected/carrier status, twins, consanguinity, adoption markers, etc.

---

## Quick Start

### Prerequisites

You need **Node.js** (version 18 or higher) installed on your computer.

#### Check if Node.js is installed:

```bash
node --version
npm --version
```

If both commands show version numbers (e.g., `v20.10.0` and `10.2.0`), you're ready to go!

#### If Node.js is NOT installed:

**Windows:**
1. Go to https://nodejs.org/
2. Download the **LTS** version (recommended)
3. Run the installer, click "Next" through all steps
4. Restart your terminal/command prompt after installation

**macOS:**
```bash
# Using Homebrew (recommended)
brew install node

# Or download from https://nodejs.org/
```

**Linux (Ubuntu/Debian):**
```bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
```

---

### Step 1: Install Dependencies (First Time Only)

Open your terminal and navigate to the project folder:

```bash
cd /path/to/pedigree-draw
```

Install the required packages:

```bash
npm install
```

This will download all necessary dependencies. You only need to do this once (or after updating the code).

---

### Step 2: Start the Server

Run the start script:

```bash
./start.sh
```

**On Windows**, use:
```bash
npm run dev
```

You should see output like:
```
==========================================
  Pedigree Draw Server Started!
==========================================

  Local:   http://localhost:5173/pedigree-draw/
  Network: http://192.168.x.x:5173/pedigree-draw/

  To stop the server, run: ./stop.sh
==========================================
```

---

### Step 3: Open in Browser

Open your web browser and go to:

- **On this computer:** http://localhost:5173/pedigree-draw/
- **From another device on the same network:** Use the Network URL shown above

---

### Step 4: Stop the Server

When you're done, stop the server:

```bash
./stop.sh
```

**On Windows**, press `Ctrl+C` in the terminal to stop the server.

---

## How to Use the Application

### Creating a New Pedigree

1. Click **"New Pedigree"** in the left panel
2. Enter a Family ID (e.g., "FAM001")

### Adding Persons

Use the toolbar at the top:

| Button | Description |
|--------|-------------|
| Square | Add Male |
| Circle | Add Female |
| Diamond | Add Unknown Sex |

### Selecting a Person

- **Click** on a person to select them
- A blue dashed border will appear around the selected person
- The right panel will show editable properties

### Adding Relationships

First **select a person**, then use these toolbar buttons:

| Button | Description |
|--------|-------------|
| Add Spouse | Creates a spouse next to selected person with connection line |
| Add Child | Creates a child below the selected person |
| Add Parents | Creates both parents above the selected person |

### Editing Properties

When a person is selected, use the right panel to edit:

- **Label**: Display name
- **Sex**: Male / Female / Unknown
- **Phenotype**: Unaffected / Affected / Carrier / Unknown
- **Status**: Deceased, Proband, Adopted, Miscarriage, Stillbirth

### Canvas Controls

| Button | Description |
|--------|-------------|
| + | Zoom in |
| - | Zoom out |
| Reset | Reset to 100% zoom, centered |
| Fit | Fit all content to screen |

You can also:
- **Drag** persons to reposition them
- **Pan** the canvas by dragging the background
- **Scroll** to zoom in/out

### Importing a PED File

1. Click **"Import PED"** in the left panel, OR
2. Drag and drop a `.ped` file onto the drop zone

### Exporting

| Button | Description |
|--------|-------------|
| Export SVG | Vector image (for editing in Illustrator, etc.) |
| Export PNG | Raster image (for documents, presentations) |
| Export PED | GATK PED format file |

### Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| **Delete** or **Backspace** | Delete selected person or relationship |
| **Escape** | Clear selection |
| **Ctrl+Z** | Undo |
| **Ctrl+Y** or **Ctrl+Shift+Z** | Redo |

### Editing Relationships

1. Click on the **connection line** between two people to select the relationship
2. The right panel will show relationship options:
   - **Add Child**: Add a Male/Female/Unknown child to this couple
   - **Partnership Status**: Married, Unmarried, Separated, Divorced
   - **Consanguinity**: Mark as consanguineous (blood relatives)
   - **Children Status**: Infertility or No children by choice

### Auto Align

If elements get messy after dragging, click the **Auto Align** button in the toolbar to automatically reposition all family members according to their generation and relationships.

---

## PED File Format

The tool supports standard GATK PED format (6 columns, whitespace-separated):

```
FamilyID  IndividualID  PaternalID  MaternalID  Sex  Phenotype
FAM001    father        0           0           1    1
FAM001    mother        0           0           2    1
FAM001    child1        father      mother      1    2
```

- **Sex**: 1 = Male, 2 = Female, 0 = Unknown
- **Phenotype**: 1 = Unaffected, 2 = Affected, 0 = Unknown
- **PaternalID/MaternalID**: Use "0" for unknown/founder

---

## Troubleshooting

### "Permission denied" when running ./start.sh

Make sure the scripts are executable:
```bash
chmod +x start.sh stop.sh
```

### Server won't start

1. Check if port 5173 is already in use:
   ```bash
   lsof -i :5173
   ```

2. Kill any existing process and try again:
   ```bash
   ./stop.sh
   ./start.sh
   ```

### Page won't load

- Make sure you're using the correct URL with `/pedigree-draw/` at the end
- Try clearing your browser cache and refreshing

### Can't access from another device

- Make sure both devices are on the same network
- Check your firewall settings allow port 5173
- Use the Network URL (not localhost)

---

## Development

### Build for Production

```bash
npm run build
```

Output will be in the `dist/` folder.

### Deploy to GitHub Pages

```bash
npm run build
# Then upload the dist/ folder contents to your GitHub Pages
```

---

## License

MIT