GINsim LogicExpression+Annotation replacement tool

A Python script to update logical expressions and annotations in GINsim .zginml files, using data from an Excel (.xlsx) spreadsheet.

Key Features

• .zginml support: Handles the GINsim zip archive format (no .ginml support).
• Node Mapping:
  • Matches nodes case-insensitively.
  • Checks both id and name attributes.
  • Automatically renames all structural references (node orders, edges) if a name change is detected via the .xlsx.
  • If a node is not found in the .xlsx or vice versa, the user is notified.
• Logic & Annotation Injection:
  • Replaces the previous logical expression (or parameters) and replaces it with the new logical expression as the first child of the <node> element.
  • Populates <annotation><comment>...</comment></annotation> sub-elements using text from the spreadsheet.
• Layout conservation: Repackages the modified model alongside all original extra files in the output.zginml file without altering the layout.

Prerequisites

• Python 3.x
• openpyxl library (for reading Excel files)

To install dependencies:

pip install openpyxl

Input File Requirements

Excel (.xlsx)

The script read the first tab of the spreadsheet. It expects a header row on line 1 (which is skipped) followed by data in three columns:

1. Node Name: The identifier used to match nodes in the model (checks against id or name in the .ginml file).
2. Logical Expression: The Boolean/logical string to be injected.
3. Annotation: Optional text to be placed in the node's comments.

XLS table format example

node	function	annotation
ECAD	!ZEB1 & !ZEB2	ZEB1 and ZEB2 suppress E-cadherin
AdhJunc	ECAD & !SRC	SRC can drive the phosphorylation and destabilization of Adherens Junction
AP1	FRA1 & JUN	Fra-1 dimerizes with Jun proteins to form the activator protein 1 (AP-1) TF
...	...	...

GINsim Model (.zginml)

A standard GINsim compressed archive. The script specifically targets the GINsim-data/regulatoryGraph.ginml file inside the archive.

Usage

Run the script by providing the path to your Excel file and your .zginml model:

python GINsim_XLS_merge.py <input_logic.xlsx> <input_model.zginml>

To push new nodes on the XLS into the GINsim model, just use the --add option:

python GINsim_XLS_merge.py <input_logic.xlsx> <input_model.zginml> --add

Output

The tool generates an output.zginml file in the current directory. This file contains:

• The updated regulatory network with new logic and annotations.
• The original DOCTYPE and XML namespaces preserved.
• All other original archive contents (mutants, settings, etc.) kept intact.

Author

Pedro T. Monteiro (https://github.com/ptgm)