match-series-batch 1.2.1

Batch non-rigid image registration with NLMeans or NLPCA denoising and stage average output.

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:

pip install match-series-batch

Usage

After installation, you can use the command line in Terminal :

match-series-batch [OPTIONS]

Example:

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:

# 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:

arch -x86_64 /usr/bin/env bash

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