Core

pd2af.transform

transform(map_or_model: Map | Model, mode: str = 'normal', layout_mode: LayoutMode | Literal['auto'] | None = 'auto', influence_pairing: InfluencePairingMode = CROSS, keep_species: bool | None = None, drop_compartments: bool | None = None, set_active: list[str] | None = None, set_inactive: list[str] | None = None, set_all_active: bool = False, set_all_inactive: bool = False, exclude_groups: tuple[str, ...] = (), exclude_rules: tuple[str, ...] = (), element_to_annotations: dict | None = None, element_to_notes: dict | None = None) -> TransformerResult

Transform a process-description map or model into an activity-flow one.

Parameters:

Name	Type	Description	Default
map_or_model	Map | Model	The input CellDesigner or SBGN-PD map, or a bare model of either language. A bare model has no geometry, so layout_mode must be "auto" or None and no layout is built.	required
mode	str	Name of the transformation mode; see :func:pd2af.modes.get_transformation_modes.	'normal'
layout_mode	LayoutMode | Literal['auto'] | None	How to lay the output out: "dot" (graphviz), "plain" (reuse the original positions), "overlay" (reuse the full original layout, dimming what is not in the model), None (no layout), or "auto" to pick from the input.	'auto'
influence_pairing	InfluencePairingMode	How to draw an influence whose source or target maps to several glyphs: "cross" (one arc per pair) or "nearest" (a single arc between the closest pair).	CROSS
keep_species	bool | None	Keep each species as its own activity instead of merging the forms of the same base entity. None takes the value the mode starts from (True for keep-reactions, False otherwise).	None
drop_compartments	bool | None	Drop the compartments, so that species differing only by compartment become a single activity and the influences that become equal merge in turn. Works with every mode; because activities merge, it requires layout_mode "dot" (or "auto") or None. None takes the value the mode starts from.	None
set_active	list[str] | None	Ids of elements to surface as activities whatever the map's structural signals say.	None
set_inactive	list[str] | None	Ids of elements to suppress, overriding the automatic activity discovery. Wins over set_all_active; an id passed to both set_active and set_inactive is an error.	None
set_all_active	bool	Make every top-level species / entity pool an activity, subunits excluded.	False
set_all_inactive	bool	Suppress activity for every element, subunits included.	False
exclude_groups	tuple[str, ...]	Identifiers of rule groups to drop from the program.	()
exclude_rules	tuple[str, ...]	Identifiers of individual rules to drop.	()
element_to_annotations	dict | None	The reader's element -> annotations side-table, to be carried onto the output elements.	None
element_to_notes	dict | None	The reader's element -> notes side-table, to be carried onto the output elements.	None

Returns:

Name	Type	Description
A	TransformerResult	class:TransformerResult holding the output map (or model, for
	TransformerResult	model input), the provenance mapping, and the carried annotation and
	TransformerResult	note side-tables.

Source code in src/pd2af/core.py

def transform(
    map_or_model: momapy.core.map.Map | momapy.core.model.Model,
    mode: str = "normal",
    layout_mode: pd2af.modes.LayoutMode | typing.Literal["auto"] | None = "auto",
    influence_pairing: pd2af.modes.InfluencePairingMode = (
        pd2af.modes.InfluencePairingMode.CROSS
    ),
    keep_species: bool | None = None,
    drop_compartments: bool | None = None,
    set_active: list[str] | None = None,
    set_inactive: list[str] | None = None,
    set_all_active: bool = False,
    set_all_inactive: bool = False,
    exclude_groups: tuple[str, ...] = (),
    exclude_rules: tuple[str, ...] = (),
    element_to_annotations: dict | None = None,
    element_to_notes: dict | None = None,
) -> TransformerResult:
    """Transform a process-description map or model into an activity-flow one.

    Args:
        map_or_model: The input CellDesigner or SBGN-PD map, or a bare model of
            either language. A bare model has no geometry, so ``layout_mode``
            must be ``"auto"`` or ``None`` and no layout is built.
        mode: Name of the transformation mode; see
            :func:`pd2af.modes.get_transformation_modes`.
        layout_mode: How to lay the output out: ``"dot"`` (graphviz),
            ``"plain"`` (reuse the original positions), ``"overlay"`` (reuse the
            full original layout, dimming what is not in the model), ``None``
            (no layout), or ``"auto"`` to pick from the input.
        influence_pairing: How to draw an influence whose source or target maps
            to several glyphs: ``"cross"`` (one arc per pair) or ``"nearest"``
            (a single arc between the closest pair).
        keep_species: Keep each species as its own activity instead of merging
            the forms of the same base entity. ``None`` takes the value the
            mode starts from (``True`` for ``keep-reactions``, ``False``
            otherwise).
        drop_compartments: Drop the compartments, so that species differing
            only by compartment become a single activity and the influences
            that become equal merge in turn. Works with every mode; because
            activities merge, it requires ``layout_mode`` ``"dot"`` (or
            ``"auto"``) or ``None``. ``None`` takes the value the mode starts
            from.
        set_active: Ids of elements to surface as activities whatever the map's
            structural signals say.
        set_inactive: Ids of elements to suppress, overriding the automatic
            activity discovery. Wins over ``set_all_active``; an id passed to
            both ``set_active`` and ``set_inactive`` is an error.
        set_all_active: Make every top-level species / entity pool an activity,
            subunits excluded.
        set_all_inactive: Suppress activity for every element, subunits
            included.
        exclude_groups: Identifiers of rule groups to drop from the program.
        exclude_rules: Identifiers of individual rules to drop.
        element_to_annotations: The reader's ``element -> annotations``
            side-table, to be carried onto the output elements.
        element_to_notes: The reader's ``element -> notes`` side-table, to be
            carried onto the output elements.

    Returns:
        A :class:`TransformerResult` holding the output map (or model, for
        model input), the provenance mapping, and the carried annotation and
        note side-tables.
    """
    transformation_mode = pd2af.modes.get_transformation_mode(mode)
    keep_species = _resolve_option("keep_species", keep_species, transformation_mode)
    drop_compartments = _resolve_option(
        "drop_compartments", drop_compartments, transformation_mode
    )
    language = pd2af.modes.get_language_from_map_or_model(map_or_model)
    influence_pairing = pd2af.modes.InfluencePairingMode(influence_pairing)
    is_model_input = isinstance(map_or_model, momapy.core.model.Model)
    if is_model_input:
        if layout_mode not in (None, pd2af.modes.AUTO):
            raise ValueError(
                f"model input supports only layout_mode 'auto' or None, "
                f"got {_format_token(layout_mode)}"
            )
        layout_mode = None
        input_map = pd2af.modes.make_map_from_model(map_or_model, language)
    else:
        input_map = map_or_model
        if layout_mode == pd2af.modes.AUTO:
            layout_mode = pd2af.modes.LayoutMode.DOT
        elif layout_mode is not None:
            layout_mode = pd2af.modes.LayoutMode(layout_mode)
    if language not in transformation_mode.compatible_languages:
        raise ValueError(
            f"transformation mode {mode!r} does not support "
            f"{_format_token(language)} input; it supports "
            + ", ".join(
                _format_token(candidate)
                for candidate in sorted(transformation_mode.compatible_languages)
            )
        )
    _check_layout_mode_is_supported(
        layout_mode, language, keep_species, drop_compartments
    )
    clingo_model, clingo_id_to_model_element = pd2af.asp.solver.solve(
        input_map,
        transformation_mode,
        set_active=set_active,
        set_inactive=set_inactive,
        set_all_active=set_all_active,
        set_all_inactive=set_all_inactive,
        exclude_groups=exclude_groups,
        exclude_rules=exclude_rules,
    )
    result = _build_map(
        input_map,
        clingo_model,
        clingo_id_to_model_element,
        mode=transformation_mode,
        language=language,
        layout_mode=layout_mode,
        influence_pairing=influence_pairing,
        keep_species=keep_species,
        drop_compartments=drop_compartments,
        element_to_annotations=element_to_annotations,
        element_to_notes=element_to_notes,
    )
    if is_model_input:
        return dataclasses.replace(result, obj=result.obj.model)
    return result

pd2af.TransformerResult dataclass

TransformerResult(obj: Map | Model | None = None, output_element_to_input_elements: FrozenIdentityMultiDict | None = None, element_to_annotations: dict | None = None, element_to_notes: dict | None = None)

Result of :func:transform: the built AF map plus provenance.

Attributes:

Name	Type	Description

Parameters:

Name	Type	Description	Default
obj	Map | Model | None		None
output_element_to_input_elements	FrozenIdentityMultiDict | None		None
element_to_annotations	dict | None		None
element_to_notes	dict | None		None