linkinpy

linkinpy is the Python core for running YAML-described bioimage-analysis methods in isolated uv environments. It provides:

• a CLI: linkinpy list, linkinpy install, linkinpy run
• spec parsing and validation
• per-spec environment management
• image loading, writing, and shared-memory transport helpers
• result normalization for single-output and multi-output methods
• Colab helper widgets
• a small Python facade API

Run commands in this document from the LinkinPy/ folder.

Development Setup

uv sync
uv run ruff check src tests
uv run pytest

Optional developer commands:

uv run ruff format .
uv run python -m build
uv run pre-commit install

The same workflow is available through make:

make sync
make lint
make test
make format
make build

CLI Tutorial

List available methods:

uv run linkinpy list ../Library/nanopyx.yaml

Install a spec for the CLI interface:

uv run linkinpy install ../Library/nanopyx.yaml --interface cli

Each spec gets its own environment under ~/.linkinpy/<spec-name>/. If the spec contains how_to_cite, the install command prints that citation text after the install summary.

Run a method and save declared outputs to a folder:

uv run linkinpy run ../Library/nanopyx.yaml eSRRF \
  --output-dir outputs \
  image=input.tif \
  magnification=2

Use explicit output destinations when needed:

uv run linkinpy run ../Library/StarDist.yaml "Predict 2D Pretrained Model" \
  --output labels=outputs/labels.tif \
  image=input.tif \
  model_name=2D_versatile_fluo

Arguments are passed as name=value. For inputs declared as np.ndarray, the CLI accepts image paths and .npy files.

Python API Tutorial

from linkinpy import LinkinPy

lp = LinkinPy("../Library/nanopyx.yaml")
print(lp.list_callables())
lp.install(interface="cli")
print(
    lp.run(
        "eSRRF",
        {"image": "input.tif", "magnification": 2},
        output_dir="outputs",
    )
)

Lower-level APIs are also public:

• load_spec / parse_spec
• EnvironmentManager
• run_spec_callable
• run_spec_callable_in_environment
• parse_run_result
• read_image / write_image

Colab Tutorial

Install LinkinPy in a notebook:

!pip install linkinpy

Mount Google Drive:

from linkinpy import mount_google_drive

mount_google_drive()

Install a selected spec:

from linkinpy import install_colab_spec

install_colab_spec("/content/LinkinPy/Library")

Run a method from installed specs:

from linkinpy import run_installed_colab_method

run_installed_colab_method(
    output_dir="/content/drive/MyDrive/LinkinPy/outputs"
)

Colab displays image and labels outputs when possible and prints metadata/path outputs in the notebook output area.

Spec Contract

Specs are YAML files. Each method declares inputs, outputs, and output.

display_name: Example Package
python_version: "3.12"
how_to_cite: "Author A, Author B. Example Package. Journal, year."

install:
  python_packages:
    - name: example-package

segment:
  callable: example_package.segment
  inputs:
    - name: image
      display_name: Input Image
      type: np.ndarray
      role: image
      required: true
  outputs:
    - name: labels
      display_name: Label Image
      type: np.ndarray
      role: labels
      format: tif
      display: true
  output:
    cli: [io]
    colab: [display, io]
    napari: [display, io]
    imagej: [display, io]
    qupath: [display, io]

outputs is the return-value contract. Tuple/list returns map by output order. Dict returns map by output name.

More Documentation

• GETTING_STARTED.md for contributor setup
• METHOD_AUTHORING.md for package authors
• CONTRIBUTING.md for the contribution workflow
• Repository tutorials for all interfaces