match-series-batch 1.2.1
Batch non-rigid image registration with NLMeans or NLPCA denoising and stage average output.
Requires Python: >=3.7

# Match-Series-Batch v1.2.1

pymatchseries is necessary.Also aequires scikit-learn to be installed for NLPCA.
make life easier

## Advantage
match-series-batch is a batch non-rigid alignment tool for microscope moving image (.dm4 format) sequences, integrating optional denoising, stage averaged plot export, automated logging and CLI calls, maint:

    •    High throughput: batch processing of multiple sample folders at once
    •    Flexible denoising: optional NLMeans, NLPCA or full skip
    •    Automatic catalogue: generates a separate, time-stamped working catalogue for each calculation, preserving all intermediate results
    •    Multiple outputs: TIFF, HSPY formats for previewing and research archiving.
    •    No human intervention: completely unattended from loading to saving

## Features
- Batch non-rigid registration for multiple image series
- Supports flexible denoising: NLMeans, NLPCA, or none
- Saves each registered frame as TIFF
- Saves full registered stack as HSPY
- Exports stage average images as TIFF and HSPY
- Customizable NLPCA parameters: patch size, number of clusters, number of components
- Automatically generates a unique working directory for each run
- Detailed logging of processing steps
- Command-line interface

## Installation
You can install `match-series-batch` via pip:
```bash
pip install match-series-batch
```

## Usage
After installation, you can use the command line in Terminal :
``` bash
match-series-batch [OPTIONS]
```

Example:
```bash
match-series-batch \
  --input  /path/to/your/input_root \
  --output /path/to/your/output_root \
  --lambda 20 \
  --prefix Aligned_ \
  --dtype uint16 \
  --denoising nlpca-spectral \
  --nlpca_patch_size 14 \
  --nlpca_n_clusters 10 \
  --nlpca_n_components 8
```

or in Jupyter notebook, can use:
```
import match_series_batch
!match-series-batch[OPTIONS]
```
or
```
import os
from tqdm import tqdm
from match_series_batch.utils import make_dirs, init_log
from match_series_batch.processing import process_one_sample

input_root  = ""
output_root = ""
make_dirs(output_root)
log_path = os.path.join(output_root, "processing_log.txt")
init_log(log_path)

folders = sorted(d for d in os.listdir(input_root) if os.path.isdir(os.path.join(input_root, d)))

for sample in tqdm(folders, desc="Batch processing"):
    in_f  = os.path.join(input_root, sample)
    out_f = os.path.join(output_root, sample)
    make_dirs(out_f)
    process_one_sample(
        sample_name=sample,
        input_folder=in_f,
        output_folder=out_f,
        log_file_path=log_path,
        regularization_lambda=20,
        filename_prefix="Final_",
        save_dtype="uint16",
        denoising_method="nlpca-spectral",
        nlpca_patch_size=14,
        nlpca_n_clusters=10,
        nlpca_n_components=12
    )
```
# Command-line Arguments Description

- `--input`
  
  Specify the root folder containing sample subfolders.  
  Each subfolder will be treated as a separate dataset for alignment.  
  (Default: set in `config.py`)

- `--output`
  
  Specify the root folder where the aligned results will be saved.  
  (Default: set in `config.py`)

- `--lambda`
  
  Set the regularization parameter for non-rigid deformation.  
  A higher value leads to smoother deformation but potentially less precise alignment.  
  A lower value allows more local deformation for better registration.  
  (Default: 20)

- `--prefix`
  
  Set the prefix for naming output files, including `.tiff`, `.dm4`, and `.hspy` files.  
  (Default: `Aligned_`)

- `--dtype`
  
  Choose the output image data type:  
  `uint8` (0–255 grayscale) or `uint16` (0–65535 grayscale).  
  Useful for preserving dynamic range.  
  (Default: `uint8`)

- `--denoising`
  
 "nlmeans" , "nlpca-spectral", "nlpca-gmm", "nlpca-kmeans" or "none"
 As set in config.py, Denoising method applied before saving images
  (Default: `nlpca-spectral`)


Notes

    •    Input folder must contain subfolders (one for each sample), each with .dm4 images.
    •    Output will include .tiff, a full aligned stack .hspy, and stage-average images.
    •    Full processing logs are recorded automatically.


## Notice for Macbook Users
If your laptop CPU is a Macbook M1/M2, MatchSeries will only work with X86_64,
Run these scripts in a terminal to generate an X86 environment for M-series processors:
```bash
# Go to the main directory
cd ~

# Printing information
echo "Downloading Miniforge3 (x86_64)..."

# Download Miniforge3 x86_64
curl -L -O https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-x86_64.sh

# Install Miniforge3 x86_64
echo "Install Miniforge3 (x86_64)..."
bash Miniforge3-MacOSX-x86_64.sh -b -p $HOME/miniforge_x86_64

# initialize Conda
echo "🔧 initialize Conda (x86_64)..."
source ~/miniforge_x86_64/bin/activate

# Switch to x86_64 architecture to run
arch -x86_64 /usr/bin/env bash <<'EOF'
    echo "being created match-x86 env..."
    source ~/miniforge_x86_64/bin/activate
    conda create -y -n match-x86 python=3.10
    conda activate match-x86

    echo "Install match-series, pyMatchSeries, hyperspy..."
    conda install -y -c conda-forge match-series
    pip install pyMatchSeries hyperspy

    echo "Installation is complete！"
```

In the Mac's own Terminal, run:
```bash
arch -x86_64 /usr/bin/env bash

source ~/miniforge_x86_64/bin/activate
conda activate match-x86
```