ID assignment

When reading an SBGN-ML file, every element follows a consistent pattern:

• Model id_ = f"{xml_id}_model"
• Layout id_ = xml_id

Both xml_id_to_model_element and xml_id_to_layout_element are keyed by the raw xml_id.

Element type	Model id_	Layout id_	Registered	Notes
Compartment	f"{glyph_id}_model"	glyph_id	yes
EntityPool / Subunit	f"{glyph_id}_model"	glyph_id	yes
Activity	f"{glyph_id}_model"	glyph_id	yes
StateVariable	f"{glyph_id}_model"	glyph_id	yes	Frozen child
UnitOfInformation	f"{glyph_id}_model"	glyph_id	yes	Frozen child
Submap	f"{glyph_id}_model"	glyph_id	yes
Terminal / Tag	f"{glyph_id}_model"	glyph_id	yes
TerminalRef / TagRef	f"{arc_id}_model"	arc_id	yes	Frozen child
StoichiometricProcess	f"{glyph_id}_model"	glyph_id	yes
Reactant	f"{arc_id}_model"	arc_id	yes	Frozen child
Product	f"{arc_id}_model"	arc_id	yes	Frozen child
LogicalOperator	f"{glyph_id}_model"	glyph_id	yes
LogicalOperatorInput	f"{arc_id}_model"	arc_id	yes	Frozen child
Modulation	f"{arc_id}_model"	arc_id	yes
Phenotype	f"{glyph_id}_model"	glyph_id	yes	In model.processes

Map, model, and layout IDs come from <map id="...">:

• map_.id_ = map_id
• model.id_ = f"{map_id}_model"
• layout.id_ = f"{map_id}_layout"

These are only set for SBGN-ML 0.3. SBGN-ML 0.2 has no map id, so the builder falls back to UUID defaults.

API

momapy.sbgn.io.sbgnml

Classes for reading and writing SBGN-ML files.

Modules:

Name	Description
reader	SBGN-ML reader classes.
writer	SBGN-ML writer classes.

Classes:

Name	Description
SBGNML0_2Reader	Class for SBGN-ML 0.2 reader objects.
SBGNML0_3Reader	Class for SBGN-ML 0.3 reader objects.
SBGNML0_3Writer	Class for SBGN-ML 0.3 writer objects.

SBGNML0_2Reader

Bases: _SBGNMLReader

Class for SBGN-ML 0.2 reader objects.

Methods:

Name	Description
check_file	Return True if the file is an SBGN-ML 0.2 document.
read	Read an SBGN-ML file and return a reader result object.

check_file classmethod

check_file(file_path: str | PathLike) -> bool

Return True if the file is an SBGN-ML 0.2 document.

Parameters:

Name	Type	Description	Default
file_path	str | PathLike	Path of the file to check.	required

Returns:

Type	Description
bool	True if the file references the SBGN-ML 0.2 namespace, False
bool	otherwise.

Source code in src/momapy/sbgn/io/sbgnml/reader.py

@classmethod
def check_file(cls, file_path: str | os.PathLike) -> bool:
    """Return `True` if the file is an SBGN-ML 0.2 document.

    Args:
        file_path: Path of the file to check.

    Returns:
        `True` if the file references the SBGN-ML 0.2 namespace, `False`
        otherwise.
    """
    try:
        with open(file_path, "rb") as f:
            for line in f:
                if b"http://sbgn.org/libsbgn/0.2" in line:
                    return True
        return False
    except Exception:
        return False

read classmethod

read(file_path: str | PathLike, return_type: Literal['map', 'model', 'layout'] = 'map', with_model: bool = True, with_layout: bool = True, with_annotations: bool = True, with_notes: bool = True, xsep: float = 0.0, ysep: float = 0.0, **options: Any) -> ReaderResult

Read an SBGN-ML file and return a reader result object.

Parameters:

Name	Type	Description	Default
file_path	str | PathLike	Path of the SBGN-ML file to read.	required
return_type	Literal['map', 'model', 'layout']	Shape of result.obj: "map" (default) returns an SBGN map, "model" returns the bare model, "layout" returns the bare layout.	'map'
with_model	bool	Whether to build the model. When False and return_type="map", the map's model is None. Defaults to True.	True
with_layout	bool	Whether to build the layout. When False and return_type="map", the map's layout is None. Defaults to True.	True
with_annotations	bool	Whether to read annotations. Defaults to True.	True
with_notes	bool	Whether to read notes. Defaults to True.	True
xsep	float	Horizontal padding added around the fitted layout elements when the map has no explicit bounding box (passed to set_fit). Defaults to 0.0.	0.0
ysep	float	Vertical padding added around the fitted layout elements when the map has no explicit bounding box (passed to set_fit). Defaults to 0.0.	0.0
options	Any	Additional reader-specific options (ignored).	{}

Returns:

Type	Description
ReaderResult	A ReaderResult whose obj is a map, model, or layout depending
ReaderResult	on return_type.

Source code in src/momapy/sbgn/io/sbgnml/reader.py

@classmethod
def read(
    cls,
    file_path: str | os.PathLike,
    return_type: typing.Literal["map", "model", "layout"] = "map",
    with_model: bool = True,
    with_layout: bool = True,
    with_annotations: bool = True,
    with_notes: bool = True,
    xsep: float = 0.0,
    ysep: float = 0.0,
    **options: typing.Any,
) -> ReaderResult:
    """Read an SBGN-ML file and return a reader result object.

    Args:
        file_path: Path of the SBGN-ML file to read.
        return_type: Shape of `result.obj`: `"map"` (default) returns an
            SBGN map, `"model"` returns the bare model, `"layout"` returns
            the bare layout.
        with_model: Whether to build the model. When `False` and
            `return_type="map"`, the map's `model` is `None`. Defaults to
            `True`.
        with_layout: Whether to build the layout. When `False` and
            `return_type="map"`, the map's `layout` is `None`. Defaults to
            `True`.
        with_annotations: Whether to read annotations. Defaults to `True`.
        with_notes: Whether to read notes. Defaults to `True`.
        xsep: Horizontal padding added around the fitted layout elements
            when the map has no explicit bounding box (passed to
            `set_fit`). Defaults to `0.0`.
        ysep: Vertical padding added around the fitted layout elements
            when the map has no explicit bounding box (passed to
            `set_fit`). Defaults to `0.0`.
        options: Additional reader-specific options (ignored).

    Returns:
        A `ReaderResult` whose `obj` is a map, model, or layout depending
        on `return_type`.
    """
    check_file_exists(file_path)
    sbgnml_document = lxml.objectify.parse(file_path)
    sbgnml_sbgn = sbgnml_document.getroot()
    (
        obj,
        annotations,
        notes,
        id_to_element,
        source_id_to_model_element,
        source_id_to_layout_element,
        source_id_to_annotations,
        source_id_to_notes,
    ) = cls._make_main_obj(
        sbgnml_map=sbgnml_sbgn.map,
        return_type=return_type,
        with_model=with_model,
        with_layout=with_layout,
        with_annotations=with_annotations,
        with_notes=with_notes,
        xsep=xsep,
        ysep=ysep,
    )
    result = ReaderResult(
        obj=obj,
        element_to_notes=notes,
        element_to_annotations=annotations,
        id_to_element=id_to_element,
        source_id_to_model_element=source_id_to_model_element,
        source_id_to_layout_element=source_id_to_layout_element,
        source_id_to_annotations=source_id_to_annotations,
        source_id_to_notes=source_id_to_notes,
        file_path=file_path,
    )
    return result

SBGNML0_3Reader

Bases: _SBGNMLReader

Class for SBGN-ML 0.3 reader objects.

Methods:

Name	Description
check_file	Return True if the file is an SBGN-ML 0.3 document.
read	Read an SBGN-ML file and return a reader result object.

check_file classmethod

check_file(file_path: str | PathLike) -> bool

Return True if the file is an SBGN-ML 0.3 document.

Parameters:

Name	Type	Description	Default
file_path	str | PathLike	Path of the file to check.	required

Returns:

Type	Description
bool	True if the file references the SBGN-ML 0.3 namespace, False
bool	otherwise.

Source code in src/momapy/sbgn/io/sbgnml/reader.py

@classmethod
def check_file(cls, file_path: str | os.PathLike) -> bool:
    """Return `True` if the file is an SBGN-ML 0.3 document.

    Args:
        file_path: Path of the file to check.

    Returns:
        `True` if the file references the SBGN-ML 0.3 namespace, `False`
        otherwise.
    """
    try:
        with open(file_path, "rb") as f:
            for line in f:
                if b"http://sbgn.org/libsbgn/0.3" in line:
                    return True
        return False
    except Exception:
        return False

read classmethod

read(file_path: str | PathLike, return_type: Literal['map', 'model', 'layout'] = 'map', with_model: bool = True, with_layout: bool = True, with_annotations: bool = True, with_notes: bool = True, xsep: float = 0.0, ysep: float = 0.0, **options: Any) -> ReaderResult

Read an SBGN-ML file and return a reader result object.

Parameters:

Name	Type	Description	Default
file_path	str | PathLike	Path of the SBGN-ML file to read.	required
return_type	Literal['map', 'model', 'layout']	Shape of result.obj: "map" (default) returns an SBGN map, "model" returns the bare model, "layout" returns the bare layout.	'map'
with_model	bool	Whether to build the model. When False and return_type="map", the map's model is None. Defaults to True.	True
with_layout	bool	Whether to build the layout. When False and return_type="map", the map's layout is None. Defaults to True.	True
with_annotations	bool	Whether to read annotations. Defaults to True.	True
with_notes	bool	Whether to read notes. Defaults to True.	True
xsep	float	Horizontal padding added around the fitted layout elements when the map has no explicit bounding box (passed to set_fit). Defaults to 0.0.	0.0
ysep	float	Vertical padding added around the fitted layout elements when the map has no explicit bounding box (passed to set_fit). Defaults to 0.0.	0.0
options	Any	Additional reader-specific options (ignored).	{}

Returns:

Type	Description
ReaderResult	A ReaderResult whose obj is a map, model, or layout depending
ReaderResult	on return_type.

Source code in src/momapy/sbgn/io/sbgnml/reader.py

@classmethod
def read(
    cls,
    file_path: str | os.PathLike,
    return_type: typing.Literal["map", "model", "layout"] = "map",
    with_model: bool = True,
    with_layout: bool = True,
    with_annotations: bool = True,
    with_notes: bool = True,
    xsep: float = 0.0,
    ysep: float = 0.0,
    **options: typing.Any,
) -> ReaderResult:
    """Read an SBGN-ML file and return a reader result object.

    Args:
        file_path: Path of the SBGN-ML file to read.
        return_type: Shape of `result.obj`: `"map"` (default) returns an
            SBGN map, `"model"` returns the bare model, `"layout"` returns
            the bare layout.
        with_model: Whether to build the model. When `False` and
            `return_type="map"`, the map's `model` is `None`. Defaults to
            `True`.
        with_layout: Whether to build the layout. When `False` and
            `return_type="map"`, the map's `layout` is `None`. Defaults to
            `True`.
        with_annotations: Whether to read annotations. Defaults to `True`.
        with_notes: Whether to read notes. Defaults to `True`.
        xsep: Horizontal padding added around the fitted layout elements
            when the map has no explicit bounding box (passed to
            `set_fit`). Defaults to `0.0`.
        ysep: Vertical padding added around the fitted layout elements
            when the map has no explicit bounding box (passed to
            `set_fit`). Defaults to `0.0`.
        options: Additional reader-specific options (ignored).

    Returns:
        A `ReaderResult` whose `obj` is a map, model, or layout depending
        on `return_type`.
    """
    check_file_exists(file_path)
    sbgnml_document = lxml.objectify.parse(file_path)
    sbgnml_sbgn = sbgnml_document.getroot()
    (
        obj,
        annotations,
        notes,
        id_to_element,
        source_id_to_model_element,
        source_id_to_layout_element,
        source_id_to_annotations,
        source_id_to_notes,
    ) = cls._make_main_obj(
        sbgnml_map=sbgnml_sbgn.map,
        return_type=return_type,
        with_model=with_model,
        with_layout=with_layout,
        with_annotations=with_annotations,
        with_notes=with_notes,
        xsep=xsep,
        ysep=ysep,
    )
    result = ReaderResult(
        obj=obj,
        element_to_notes=notes,
        element_to_annotations=annotations,
        id_to_element=id_to_element,
        source_id_to_model_element=source_id_to_model_element,
        source_id_to_layout_element=source_id_to_layout_element,
        source_id_to_annotations=source_id_to_annotations,
        source_id_to_notes=source_id_to_notes,
        file_path=file_path,
    )
    return result

SBGNML0_3Writer

Bases: Writer

Class for SBGN-ML 0.3 writer objects.

The single SBGN-ML writer (registered under both sbgnml and sbgnml-0.3). All serialization logic lives in module-level functions; this class only provides the write entry point.

Methods:

Name	Description
write	Write an SBGN map to an SBGN-ML file.

write classmethod

write(obj: SBGNMap, file_path: str | PathLike, element_to_annotations: dict | None = None, element_to_notes: dict | None = None, source_id_to_model_element: dict | None = None, source_id_to_layout_element: dict | None = None, source_id_to_annotations: dict | None = None, source_id_to_notes: dict | None = None, with_annotations: bool = True, with_notes: bool = True, **options: Any) -> WriterResult

Write an SBGN map to an SBGN-ML file.

Parameters:

Name	Type	Description	Default
obj	SBGNMap	The SBGN map to serialize.	required
file_path	str | PathLike	Destination file path.	required
element_to_annotations	dict | None	Optional per-element annotation dict.	None
element_to_notes	dict | None	Optional per-element notes dict.	None
source_id_to_model_element	dict | None	Optional source ID to model element mapping from ReaderResult.	None
source_id_to_layout_element	dict | None	Optional source ID to layout element mapping from ReaderResult.	None
source_id_to_annotations	dict | None	Optional per-source-id annotations from ReaderResult.	None
source_id_to_notes	dict | None	Optional per-source-id notes from ReaderResult.	None
with_annotations	bool	Whether to write annotations.	True
with_notes	bool	Whether to write notes.	True
options	Any	Additional options (accepted and ignored).	{}

Returns:

Type	Description
WriterResult	WriterResult containing the written object and file path.

Source code in src/momapy/sbgn/io/sbgnml/writer.py

@classmethod
def write(
    cls,
    obj: SBGNMap,
    file_path: str | os.PathLike,
    element_to_annotations: dict | None = None,
    element_to_notes: dict | None = None,
    source_id_to_model_element: dict | None = None,
    source_id_to_layout_element: dict | None = None,
    source_id_to_annotations: dict | None = None,
    source_id_to_notes: dict | None = None,
    with_annotations: bool = True,
    with_notes: bool = True,
    **options: typing.Any,
) -> WriterResult:
    """Write an SBGN map to an SBGN-ML file.

    Args:
        obj: The SBGN map to serialize.
        file_path: Destination file path.
        element_to_annotations: Optional per-element annotation dict.
        element_to_notes: Optional per-element notes dict.
        source_id_to_model_element: Optional source ID to model
            element mapping from ReaderResult.
        source_id_to_layout_element: Optional source ID to layout
            element mapping from ReaderResult.
        source_id_to_annotations: Optional per-source-id annotations
            from ReaderResult.
        source_id_to_notes: Optional per-source-id notes from
            ReaderResult.
        with_annotations: Whether to write annotations.
        with_notes: Whether to write notes.
        options: Additional options (accepted and ignored).

    Returns:
        WriterResult containing the written object and file path.
    """
    if obj.model is None or obj.layout is None:
        raise ValueError("cannot write a map without both a model and a layout")
    check_parent_dir_exists(file_path)
    if element_to_annotations is None:
        element_to_annotations = {}
    if element_to_notes is None:
        element_to_notes = {}
    writing_context = WritingContext(
        map_=obj,
        element_to_annotations=element_to_annotations,
        element_to_notes=element_to_notes,
        source_id_to_model_element=source_id_to_model_element,
        source_id_to_layout_element=source_id_to_layout_element,
        source_id_to_annotations=source_id_to_annotations,
        source_id_to_notes=source_id_to_notes,
        with_annotations=with_annotations,
        with_notes=with_notes,
    )
    sbgnml_sbgn = make_lxml_element("sbgn", nsmap=NSMAP)
    sbgnml_map = make_sbgnml_map(writing_context)
    sbgnml_sbgn.append(sbgnml_map)
    with open(file_path, "w", encoding="utf-8") as f:
        f.write(
            lxml.etree.tostring(
                sbgnml_sbgn, pretty_print=True, xml_declaration=True
            ).decode()
        )
    return WriterResult(obj=obj, file_path=file_path)