# Lab Toolkit

A curated set of lab automation scripts and utilities I built over the years.
This repo is designed as a single showcase with clear docs, examples, and reproducible usage.

Highlights:
- Automation tools for imaging, sequencing, and FACS data cleanup.
- Practical, production-used scripts with real workflows.
- Fast to browse and easy to demo for hiring teams.

## Quick start

1) Install Python 3.9+.
2) Install common dependencies:

```bash
pip install pandas pillow rich tqdm alive-progress opencv-python numpy matplotlib openpyxl
```

3) Pick a tool from `tools/` and run it from its folder.

Notes:
- Some tools are Windows-specific (they open Excel or use Windows file dialogs).
- `facs-transformer.html` is a local web app that pulls libraries from CDNs.

## Tools

### FACS Data Transformer (web)

Transform hierarchical FACS gating exports into a melted X/Y table.

- Location: `tools/facs-transformer/facs-transformer.html`
- Example input: `tools/facs-transformer/examples/13-Jan-2026.xlsD.xls`
- Output: `melted_facs_data.xlsx` (downloaded by the app)

Usage:
1) Open the HTML file in a browser.
2) Upload the Excel file.
3) Reorder/select columns and samples (drag-and-drop), optionally add Sample Alias.
4) Preview the melted table and download the output.

Layout features:
- Save layout (selected columns + order, selected samples + order/duplicates, aliases).
- Import layout later (overwrites current selections).

### GetBE v5

Generate a `BE.xlsx` control file for the ImageMerger tools by scanning
subfolders with images and calculating grid sizes.

- Location: `tools/getbe/getbe_v5.py`
- Output: `BE.xlsx` in the chosen root directory

Usage:
```bash
python tools/getbe/getbe_v5.py "C:\path\to\image\root"
```

Notes:
- The script builds `layout_file` names using a lab-specific folder naming
  convention. If your folder naming differs, edit the `layout_file` logic.

### ImageMerger (v5, v7, v8, v9, v10.1)

Create image grids based on `BE.xlsx` and optional layout Excel files.

- Location: `tools/image-merger/`
- Inputs: `BE.xlsx` (generated by GetBE), layout files referenced in `BE.xlsx`
- Outputs:
  - v5: `*_grid.jpg`
  - v7/v8/v9/v10.1: `*_grid.png`

Usage (v9 and v10.1):
```bash
python tools/image-merger/image_merger_v10_1.py --path "C:\path\to\folder\with\BE.xlsx"
```

Version notes:
- v5: multithreaded with `alive-progress`, basic image handling.
- v7: 16-bit TIFF support and per-image progress bars.
- v8: logging + tqdm for task progress.
- v9: rich progress, improved layout checks.
- v10.1: faster load/save path, uses in-memory image loading.

### MultiCropper

Interactively select a crop region and apply it to every image in a folder.

- Location: `tools/multi-cropper/multi_cropper.py`
- Output: `cropped/` subfolder (or user-specified output directory)

Usage:
```bash
python tools/multi-cropper/multi_cropper.py
```

### Sequence Chopper

Split long DNA sequences into fixed-length chunks and export primer lists.

- Location: `tools/sequence-chopper/sequence_chopper.py`
- Output: `Primers_output.txt`

Usage:
1) Edit the `f` and `r` sequences at the top of the file.
2) Adjust the chunk size in the call to `ChopSeq(...)`.
3) Run the script.

### sgRNA Primer Bulk

Generate oligo sequences from a list of names and target DNA sequences in Excel.

- Location: `tools/sgrna-primer-bulk/sgrna_primer_bulk.py`
- Input: Excel file with columns `name` and `DNA sequence` (first two columns)
- Output: A new sheet named `Modified Sequences` in the same Excel file

Usage:
```bash
python tools/sgrna-primer-bulk/sgrna_primer_bulk.py "C:\path\to\input.xlsx"
```

Notes:
- Prompts to remove a trailing NGG if present.
- Opens Excel after writing the output sheet (Windows).

### SlidesMiner

Extract slide changes from a screen recording, then build a PDF.

- Location: `tools/slides-miner/slides_miner.py`
- Input: `.mp4` file
- Output: `screenshots/` and a PDF in the current directory

Usage:
```bash
python tools/slides-miner/slides_miner.py path\to\video.mp4 --threshold 0.02 --reference-points 100
```

### utMutator

Convert RNA to DNA by replacing all `U` with `T`.

- Location: `tools/ut-mutator/ut_mutator.py`

Usage:
```bash
python tools/ut-mutator/ut_mutator.py -i "AUGCUU"
```

### Keyence Imaging Macros

Keyence `.mrf` macro files used to automate HTS imaging when autofocus is unreliable.

- Location: `tools/keyence-macros/`
- Files: Plate layouts and capture routines for 24/48/96-well plates and iBidi 96Square

## Repo structure

```
tools/
  facs-transformer/
  getbe/
  image-merger/
  multi-cropper/
  sequence-chopper/
  sgrna-primer-bulk/
  slides-miner/
  ut-mutator/
```

## GitHub Pages (optional)

If you want a simple landing page for recruiters:

1) In GitHub, go to repo Settings -> Pages.
2) Set source to `main` and folder to `/ (root)`.
3) Add a small `index.html` or a Markdown landing page later if desired.

I can generate a minimalist landing page on request.