limnode.py

The limnode.py file location depends on the installation type:

%userprofile%\AppData\Local\Programs\NIS-Express\Python\Lib\site-packages\limnode.py

"C:\Program Files\NIS-Express\Python\Lib\site-packages\limnode.py"

This reference is extracted from the documentation stings from the limnode.py.

Type aliases and protocols

List of type aliases

`CellData`	`int \| float \| str \| None`
`ColData`	`list[int \| None] \| list[float \| None] \| list[str \| None] \| ArrayLike`
`MultiColData`	`ColData \| list[ColData] \| ArrayLike`
`SafeColSpec`	`list[str] \| list[int] \| re.Pattern \| Callable[[str, dict[str, Any]], bool] \| None`
`AnyColorDef`	`int \| str \| tuple[int, int, int]`
`UserParTuple`	`tuple[int \| float \| str, ...]`
`LoopDefs`	`list[LoopDef]`
`AnyInDef`	`InputChannelDef \| InputBinaryDef \| InputTableDef \| None`
`AnyOutDef`	`OutputChannelDef \| OutputBinaryDef \| OutputTableDef`
`InDefTuple`	`tuple[AnyInDef, ...]`
`OutDefTuple`	`tuple[AnyOutDef, ...]`
`AnyInData`	`InputChannelData \| InputBinaryData \| InputTableData \| None`
`AnyOutData`	`OutputChannelData \| OutputBinaryData \| OutputTableData`
`InDataTuple`	`tuple[AnyInData, ...]`
`OutDataTuple`	`tuple[AnyOutData, ...]`

class ArrayLike(Protocol)

Numpy-compatible array object passed between GA3 and Python code.

ArrayLike.ndim: int
ArrayLike.shape: tuple[int, ...]

class LimTableLike(Protocol)

GA3 table object used to exchange tabular data and table schemas.

LimTableLike.tableName: str
LimTableLike.tableMetadata: dict[str, Any]
LimTableLike.colIdList: list[str]
LimTableLike.colMetadataList: list[dict[str, Any]]

class MplFigureLike(Protocol)

Matplotlib-like figure or canvas that can be stored as a GA3 result image.

class ExperimentLoopType(enum.IntEnum)

GA3 experiment loop kind, such as well, site, time, or Z-stack.

ExperimentLoopType.loopTypeUnknown = 0
ExperimentLoopType.loopTypePlate = 1
ExperimentLoopType.loopTypeWell = 2
ExperimentLoopType.loopTypeXYSite = 3
ExperimentLoopType.loopTypeTLapse = 4
ExperimentLoopType.loopTypeZStack = 5
ExperimentLoopType.loopTypeCount = 6
ExperimentLoopType.loopTypeSlide = 7
ExperimentLoopType.loopTypeRegion = 8
ExperimentLoopType.loopTypeTemporary = 9

Common base types

class Node

GA3 processing node that owns the parameter represented by this object.

Node.name: str
Node.uuid: str
Node.defaultName: str

class LoopDef

One GA3 experiment loop available to a Python node invocation.

LoopDef.name: str
LoopDef.type: ExperimentLoopType
LoopDef.index: int

class ParameterDef

Common GA3 parameter definition metadata for input and output ports.

ParameterDef.parentNode: Node
ParameterDef.parName: str
ParameterDef.parUuid: str
ParameterDef.parIsInput: bool
ParameterDef.loopDefList: list[LoopDef]

ParameterDef.loopNames(
    loop_type: ExperimentLoopType | list[ExperimentLoopType] | None = None
) -> list[str]

Return loop names available to this parameter.

Parameters

loop_type Optional loop type, list of loop types, or None for all loops.

Raises

TypeError if loop_type is not None, ExperimentLoopType, or a list of ExperimentLoopType.

ParameterDef.format_coordinates(
    coordinates: tuple[int],
    sep: str = '_',
    one_based_indexes: bool = True,
    leading_zeros: int = 0
) -> str

Format loop coordinates into a compact label.

Use this when naming files, result rows, or diagnostic messages from ctx.outCoordinates or ctx.inpParameterCoordinates.

Parameters

`coordinates`	Zero-based coordinate tuple in the same order as loopDefList.
`sep`	Separator inserted between coordinate parts.
`one_based_indexes`	Convert indexes to one-based labels when True.
`leading_zeros`	Minimum number of digits for each index.

class Metadata

Image metadata shared by GA3 channel and binary parameters.

Metadata.componentCount: int
Metadata.bitsPerComponent: int
Metadata.size: tuple[int, int, int]
Metadata.calibration: tuple[float, float, float]
Metadata.alignment: int
Metadata.isRGB: bool

Metadata.withDifferentSize(
    size: tuple[int, int, int],
    calibration: tuple[float, float, float] | None = None
) -> Metadata

Set output metadata to a different image size.

Call this in output(…) when an output image or binary has dimensions that differ from the input used to initialize the output definition.

Parameters

`size`	Output size as (X, Y, Z).
`calibration`	Optional calibration tuple as (X, Y, Z).

The `output(...)` function

output(...) declares the Python node outputs before the node runs.

InDefTuple: TypeAlias = tuple[AnyInDef, ...]
AnyInDef: TypeAlias = InputChannelDef|InputBinaryDef|InputTableDef|None

OutDefTuple: TypeAlias = tuple[AnyOutDef, ...]
AnyOutDef: TypeAlias = OutputChannelDef|OutputBinaryDef|OutputTableDef

UserParTuple: TypeAlias = tuple[int|float|str, ...]

def output(inp: limnode.InDefTuple,
           out: limnode.OutDefTuple,
           par: limnode.UserParTuple) -> None:
    ...

class InputChannelDef(ParameterDef, Metadata)

Read-only definition of a GA3 input channel available in output(…).

Use this to inspect the input channel name, color, size, calibration, and bit depth when defining outputs. Do not modify input parameter definitions.

InputChannelDef.channelName: str
InputChannelDef.channelColor: int

class OutputChannelDef(ParameterDef, Metadata)

Writable definition of a GA3 output channel configured in output(…).

OutputChannelDef.assignedParName: str | None = None
OutputChannelDef.channelName: str | None = None
OutputChannelDef.channelColor: int | None = None

OutputChannelDef.assign(
    param: InputChannelDef
) -> OutputChannelDef

Make this output channel reuse an input channel definition.

Use this when the output should keep the input channel name, color, size, calibration, component count, and bit depth.

Parameters

param Input channel definition to assign.

OutputChannelDef.makeNewMono(
    name: str,
    color: AnyColorDef
) -> OutputChannelDef

Define a new mono output channel.

Parameters

`name`	Channel name shown in GA3.
`color`	Channel color as “#RRGGBB”, integer RGB, or (R, G, B).

OutputChannelDef.makeNewRgb(
    name: str | None = None
) -> OutputChannelDef

Define a new RGB output channel.

Parameters

name Channel name shown in GA3.

class InputBinaryDef(ParameterDef, Metadata)

Read-only definition of a GA3 input binary available in output(…).

Use this to inspect the input binary name, color, size, calibration, and bit depth when defining outputs. Do not modify input parameter definitions.

InputBinaryDef.binaryName: str
InputBinaryDef.binaryColor: int

class OutputBinaryDef(ParameterDef, Metadata)

Writable definition of a GA3 output binary configured in output(…).

OutputBinaryDef.assignedParName: str | None = None
OutputBinaryDef.binaryName: str | None = None
OutputBinaryDef.binaryColor: int | None = None

OutputBinaryDef.assign(
    param: InputBinaryDef
) -> OutputBinaryDef

Make this output binary reuse an input binary definition.

Use this when the output should keep the input binary name, color, size, calibration, component count, and bit depth.

Parameters

param Input binary definition to assign.

OutputBinaryDef.makeNew(
    name: str,
    color: AnyColorDef
) -> OutputBinaryDef

Define a new binary output.

Parameters

`name`	Binary name shown in GA3.
`color`	Binary color as “#RRGGBB”, integer RGB, or (R, G, B).

class InputTableDef(ParameterDef)

Read-only definition of a GA3 input table available in output(…).

Use this to inspect or copy the input table schema and accumulation metadata when defining outputs. Do not modify input parameter definitions.

InputTableDef.tableDef: LimTableLike

InputTableDef.accumulatedOver() -> list[str]

Return names of loops already accumulated in this input table.

class OutputTableDef(ParameterDef)

Writable definition of a GA3 output table configured in output(…).

OutputTableDef.assignedParName: str
OutputTableDef.tableDef: LimTableLike

OutputTableDef.assign(
    inParam: InputTableDef
) -> OutputTableDef

Make this output table reuse an input table schema.

Parameters

inParam Input table definition to assign.

OutputTableDef.makeEmpty(
    name: str,
    inParam: InputTableDef | None = None
) -> OutputTableDef

Create a named output table with no copied columns.

If inParam is an accumulated input table, the accumulation metadata is preserved so GA3 interprets the output rows at the same loop level.

Parameters

`name`	Table name shown in GA3.
`inParam`	Optional input table whose accumulation metadata should be preserved.

OutputTableDef.makeNew(
    name: str,
    inParam: InputTableDef | None = None
) -> OutputTableDef

Create a named output table.

With an input table, the input schema is copied and renamed. Without an input table, loop-index columns are created automatically.

Parameters

`name`	Table name shown in GA3.
`inParam`	Optional input table definition to copy.

OutputTableDef.makeResult(
    name: str,
    inParam: InputTableDef | None = None
) -> OutputTableDef

Create a result-table shell for rendered outputs.

Use this before OutputTableData.withMplImage(…) or other result helpers that write HTML and InitialState rows.

Parameters

`name`	Result table name shown in GA3.
`inParam`	Optional input table definition to copy.

OutputTableDef.withLoopCols(
    newColNames: list[str] | None = None
) -> OutputTableDef

Add GA3 loop-index columns to the output table.

Parameters

newColNames Optional list that receives added column titles.

OutputTableDef.withEntityCol(
    newColNames: list[str] | None = None
) -> OutputTableDef

Add the GA3 Entity column used by object-linked table rows.

OutputTableDef.withObjectCols(
    newColNames: list[str] | None = None
) -> OutputTableDef

Add 2D object-link columns Entity and ObjectId.

OutputTableDef.withObject3dCols(
    newColNames: list[str] | None = None
) -> OutputTableDef

Add 3D object-link columns Entity and ObjectId.

OutputTableDef.withIntCol(
    title: str,
    unit: str | None = None,
    feature: str | None = None,
    id: str | None = None
) -> OutputTableDef

Add an integer column to the output table.

OutputTableDef.withFloatCol(
    title: str,
    unit: str | None = None,
    feature: str | None = None,
    id: str | None = None
) -> OutputTableDef

Add a floating-point column to the output table.

OutputTableDef.withStringCol(
    title: str,
    unit: str | None = None,
    feature: str | None = None,
    id: str | None = None
) -> OutputTableDef

Add a string column to the output table.

OutputTableDef.accumulatedOver() -> list[str]

Return names of loops this output table is marked as accumulated over.

OutputTableDef.setAccumulatedOver(
    *args,
    *args
) -> OutputTableDef

Mark this table as accumulated over the named loops.

Parameters

*args Loop names to accumulate over.

OutputTableDef.setUnaccumulated() -> OutputTableDef

Mark this table as a per-frame table.

OutputTableDef.setAccumulatedOverZStack() -> OutputTableDef

Mark this table as accumulated over Z-stack loops.

OutputTableDef.setAccumulatedOverTimeLapse() -> OutputTableDef

Mark this table as accumulated over time-lapse loops.

OutputTableDef.setAccumulatedOverMultiPoint() -> OutputTableDef

Mark this table as accumulated over multipoint/site loops.

OutputTableDef.setAccumulatedOverAll() -> OutputTableDef

Mark this table as accumulated over every available loop.

The `run(...)` function

run(...) receives input data, fills output data, and may use RunContext to inspect execution state.

InDataTuple: TypeAlias = tuple[AnyInData, ...]
AnyInData: TypeAlias = InputChannelData|InputBinaryData|InputTableData|None

OutDataTuple: TypeAlias = tuple[AnyOutData, ...]
AnyOutData: TypeAlias = OutputChannelData|OutputBinaryData|OutputTableData

UserParTuple: TypeAlias = tuple[int|float|str, ...]

def run(inp: limnode.InDataTuple,
        out: limnode.OutDataTuple,
        par: limnode.UserParTuple,
        ctx: limnode.RunContext) -> None:
    pass

class ArrayData

Runtime GA3 image array container used by channel and binary data ports.

ArrayData.data: ArrayLike | None

class RecordedData

Runtime GA3 recorded-data side table attached to channel and binary data.

RecordedData.recdata: LimTableLike | None

class InputChannelData(
           ParameterDef, Metadata, ArrayData, RecordedData
)

Read-only GA3 input channel data available in run(…).

Read the data array and metadata, but do not replace or modify the input array. Write results through the corresponding output data object instead.

InputChannelData.channelName: str

class OutputChannelData(
           ParameterDef, Metadata, ArrayData, RecordedData
)

Writable GA3 output channel data filled in run(…).

OutputChannelData.copyRecordedDataFrom(
    other: RecordedData
) -> None

Copy recorded per-pixel/per-object data from another channel or binary.

class InputBinaryData(
           ParameterDef, Metadata, ArrayData, RecordedData
)

Read-only GA3 input binary data available in run(…).

Read the data array and metadata, but do not replace or modify the input array. Write results through the corresponding output data object instead.

InputBinaryData.binaryName: str

class OutputBinaryData(
           ParameterDef, Metadata, ArrayData, RecordedData
)

Writable GA3 output binary data filled in run(…).

OutputBinaryData.copyRecordedDataFrom(
    other: RecordedData
) -> None

Copy recorded per-pixel/per-object data from another channel or binary.

class InputTableData(ParameterDef, RecordedData)

Read-only GA3 input table data available in run(…).

Use helper methods to read columns or DataFrames from the table. Do not modify input table data; write derived rows through OutputTableData.

InputTableData.data: LimTableLike

InputTableData.colArray(
    cols: str | int | SafeColSpec = None
) -> ArrayLike | list[ArrayLike]

Return numpy ndarray or a list there of for specified columns.

If cols is scalar ndarray is returned otherwise a list is returned instead.

Column specifier:

column name, ID or index returns single column
list of column names, IDs or indexes returns list of columns (must be present)
None return all columns
re.Pattern return columns where fullmatch succeeded on column ID or Title
Callable[[str, dict], bool] returns columns where callable returns True for (ID, Metadata)

When column names, IDs or indexes are specified explicitly in a list they must be present otherwise and AssertError is raised.

Parameters

cols col name, id or index or a list there of or a Pattern or Callable

Raises

`ValueError`	if a column explicitly specified (by name, id or index) is not found
`TypeError`	if cols are not of requested type

InputTableData.dataFrame(
    use_col_ids: bool = False,
    no_hidden: bool = False,
    no_loops: bool = False,
    no_loop_indexes: bool = False,
    no_bin: bool = False,
    no_bin_id: bool = False,
    no_bin_entity: bool = False,
    no_well: bool = False,
    no_file: bool = False,
    excl: SafeColSpec = None,
    incl: SafeColSpec = None,
    no_*
) -> 'pd.DataFrame'

Return Pandas DataFrame with all columns except as specified.

By default all columns are returned. If no_* or excl kwarg is present, matching columns are removed. If incl is present, matching columns are added (after exclusion)

Parameters

`use_col_ids`	columns are indexed by column ids and not by column titles
`excl`	exclude any column
`incl`	include any column
`no_*`	exclude specific system column/hidden columns

Raises

AssertError if a column explicitly specified column (by name, id or index) is not found

InputTableData.metaDataFrame() -> 'pd.DataFrame'

Return Pandas DataFrame describing input table columns.

class OutputTableData(ParameterDef, RecordedData)

Writable GA3 output table data filled in run(…).

OutputTableData.data: LimTableLike | None

OutputTableData.withColDataFrom(
    *args: Sequence[InputTableData],
    remaining_cols: list[str] | None = None,
    *args
) -> OutputTableData

Fill matching output columns from input tables or Pandas objects.

Columns are matched by output column IDs. This is useful after makeNew(name, input_table) when most output columns should keep the input values and only derived columns need to be filled separately.

Parameters

`remaining_cols`	Optional list that receives output column IDs not filled.
`*args`	InputTableData, pandas.DataFrame, or pandas.Series sources.

OutputTableData.withColData(
    cols: str | int | SafeColSpec,
    data: MultiColData
) -> OutputTableData

Fill table with column data and return self.

Column specifier:

column name, ID or index returns single column
list of column names, IDs or indexes returns list of columns (must be present)
None return all columns
re.Pattern return columns where fullmatch succeeded on column ID or Title
Callable[[str, dict], bool] returns columns where callable returns True for (ID, Metadata)

The data must have same length as cols.

When column names, IDs or indexes are specified explicitly in a list they must be present otherwise and AssertError is raised.

Parameters

`cols`	col name, id or index or a list there of or a Pattern or Callable
`data`	list of values, 1D nd array or a list of these or 2D nd array

Raises

`ValueError`	if a column explicitly specified column (by name, id or index) is not found
`TypeError`	if cols or data are not of requested type

OutputTableData.dataFrame(
    use_col_ids: bool = False
) -> 'pd.DataFrame'

Return Pandas DataFrame with all columns.

Parameters

use_col_ids columns are indexed by column ids and not by column titles

OutputTableData.withDataFrame(
    df: 'pd.DataFrame',
    cols: str | int | SafeColSpec = None
) -> OutputTableData

Fill table with Pandas DataFrame.

Column specifier:

column name, ID or index returns single column
list of column names, IDs or indexes returns list of columns (must be present)
None return all columns
re.Pattern return columns where fullmatch succeeded on column ID or Title
Callable[[str, dict], bool] returns columns where callable returns True for (ID, Metadata)

When column names, IDs or indexes are specified explicitly in a list they must be present otherwise and AssertError is raised.

Parameters

`df`	Pandas DataFrame
`cols`	col name, id or index or a list there of or a Pattern or Callable

Raises

`ValueError`	if a column explicitly specified (by name, id or index) is not found
`TypeError`	if cols or data are not of requested type

OutputTableData.withMplImage(
    loopCoordinates: tuple[int],
    plt: MplFigureLike | tuple[MplFigureLike, MplFigureLike],
    name: str | None = None,
    iconres: str | None = None,
    objectFit: str | None = None,
    tableRowVisibility: str | None = None,
    savefig_kwargs: dict = {'format': 'png'}
) -> OutputTableData

Store a matplotlib figure in a result table.

The output table must be defined with OutputTableDef.makeResult(…). Passing a tuple stores separate light-theme and dark-theme images.

Parameters

`loopCoordinates`	Usually ctx.outCoordinates for the current result row.
`plt`	Matplotlib figure/canvas, or (light, dark) figure/canvas pair.
`name`	Optional result tab name.
`iconres`	Optional GA3 icon resource name.
`objectFit`	Optional CSS object-fit value for the image view.
`tableRowVisibility`	Optional result-row visibility mode.
`savefig_kwargs`	Keyword arguments used when plt.savefig(…) is called.

class RunContext

GA3 execution context for the current run(…) invocation.

RunContext.inpFilename: str
RunContext.outFilename: str
RunContext.inpParameterCoordinates: tuple[tuple[int]]
RunContext.outCoordinates: tuple[int]
RunContext.programLoopsOver: list[str] | None
RunContext.programCoordinateIndexes: tuple[int] | None
RunContext.programPass: int
RunContext.programIndex: int
RunContext.programLength: int
RunContext.finalCall: bool
RunContext.tempPath: str

RunContext.shouldAbort: bool

Return True when GA3 has requested cancellation of the current run.

The `build(...)` function

build(...) can return a program object to control how GA3 invokes run(...) over loops.

UserParTuple: TypeAlias = tuple[int|float|str, ...]

def build(par: limnode.UserParTuple,
          loops: limnode.LoopDefs) -> limnode.Program | None:
    return None

class Program

GA3 invocation plan returned by build(…) to select loops handled in Python.

Program.allLoopDefs: list[LoopDef]
Program.overLoops: list[str] = field(default_factory=list, init=False)

Program.overZStack() -> Program

Run the program over Z-stack loops instead of per-Z invocation.

Program.overTimeLapse() -> Program

Run the program over time-lapse loops instead of per-time invocation.

Program.overMultiPoint() -> Program

Run the program over multipoint/site loops instead of per-site invocation.

Program.overAll() -> Program

Run the program over all available loops.

class ReduceProgram(Program)

GA3 reduction program that accumulates selected loops before final output.

class TwoPassProgram(Program)

GA3 two-pass program for algorithms that need a scan pass before output.

Utility functions

def print(
    *args,
    **kwargs
):
    pass

Write to the GA3 Python output stream from managed child execution.

Import this instead of builtins.print inside scripts that run through child_main(…). The text is forwarded to the host process output.

def log(
    *args,
    **kwargs
):
    pass

Append diagnostic text to the NIS Python log when NIS_LOG_PATH is set.

def separateLabeledImage(
    src: ArrayLike
) -> ArrayLike:
    pass

Separate touching labels in a 2D labeled image.

Pixels that touch a higher-valued label in their 3x3 neighborhood are set to zero. Use this to create a one-pixel background gap between adjacent labeled objects before measurement or display.

Parameters

src 2D numpy ndarray of integer labels.

def separateLabeledImage3d(
    src: ArrayLike
) -> ArrayLike:
    pass

Separate touching labels in a 3D labeled image.

Keeps the largest remaining connected component for each original label and clears voxels that touch a higher-valued label in their 3x3x3 neighborhood.

Parameters

src 3D numpy ndarray of integer labels.

Keyboard shortcuts Workflows

limnode.py

Type aliases and protocols

Common base types

The output(...) function

The run(...) function

The build(...) function

Utility functions

The `output(...)` function

The `run(...)` function

The `build(...)` function