stonpy.core module

The main module for stonpy. The STON class is the interface with the Neo4j database.

class stonpy.core.STON(uri, user, password)

Bases: object

Main class for storing, retrieving and querying maps from a Neo4j database

Variables:

• uri – the URI of the running Neo4j database

• user – the username

• password – the password

Here is an example:

import stonpy

URI = "my_uri"
USER = "my_user"
PASSWORD = "my_password"

ston = stonpy.STON(URI, USER, PASSWORD)

create_map(sbgn_map, map_id, verbose=False)

Add an SBGN map to the database (with the CREATE instruction).

Parameters:

• sbgn_map (str or libsbgnpy.libsbgn.map) – the SBGN map, either a path to an SBGN-ML file or an SBGN map object

• map_id (str, optional) – the ID of the SBGN map

Here is an example:

sbgn_file = "insulin.sbgn"
ston.graph.delete_all()

ston.create_map(sbgn_file, map_id="id1")

assert ston.has_map("id1") is True

delete_map(map_id)

Delete an SBGN map from the database.

Deletes all maps with this ID from the database.

Parameters:

map_id (str) – the ID of the SBGN map

Here is an example:

sbgn_file = "insulin.sbgn"
ston.graph.delete_all()
ston.create_map(sbgn_file, "id1")

ston.delete_map("id1")

assert ston.has_map("id1") is False

get_map(map_id)

Retrieve an SBGN map with given ID from the database and returns it.

If no map is retrieved, returns None. If multiple maps are retrieved, only the first one is returned.

Note: This method is significantly faster when the Neo4j APOC core Library optional dependency is installed.

Parameters:

map_id (str) – the ID of the SBGN map to retrieve

Returns:

the SBGN map or None

Return type:

libsbgnpy.libsbgn.map or None

Here is an example:

sbgn_file = "insulin.sbgn"
ston.create_map(sbgn_file, "id1")

sbgn_map = ston.get_map("id1")
print(sbgn_map)

get_map_to_sbgn_file(map_id, sbgn_file)

Retrieve a map with given ID from the database and write it to the given SBGN-ML file.

Nothing is done if no map is retrieved. If multiple maps are retrieved, only the first one is written to the SBGN-ML file.

Parameters:

• map_id (str) – the ID of the SBGN map to retrieve

• sbgn_file (str) – the path of the the SBGN-ML where to write the retrieved map

Here is an example:

sbgn_file = "insulin.sbgn"
ston.graph.delete_all()
ston.create_map(sbgn_file, "id1")

ston.get_map_to_sbgn_file("id1", "insulin_exported.sbgn")
with open("insulin_exported.sbgn") as f:
    print("".join(f.readlines()[:10]))

property graph

The handle to the graph in the database. The graph is of type py2neo.Graph.

The graph handle can be used to delete all data from the database, for example:

ston.graph.delete_all()

has_map(map_id=None, sbgn_map=None)

Check whether the database contains a given SBGN map

If only a map ID is provided, checks whether the database contains a map with that ID. If only an SBGN map is provided, checks whether the database contains this map. If both a map ID and an SBGN map are provided, checks whether the database contains this map with this ID.

Parameters:

• map_id (str, optional) – the ID of the SBGN map, default is None

• sbgn_map – the SBGN map, either a path to an SBGN-ML file or an SBGN map object, default is None

Returns:

True if the database contains the SBGN map, False otherwise

Return type:

bool

Here is an example:

sbgn_file = "insulin.sbgn"
ston.graph.delete_all()
ston.create_map(sbgn_file, map_id="id1")

assert ston.has_map("id1") is True
assert ston.has_map(sbgn_map=sbgn_file) is True
assert ston.has_map(map_id="id1", sbgn_map=sbgn_file) is True
assert ston.has_map(map_id="id2", sbgn_map=sbgn_file) is False

query_to_map(query, complete=True, merge_records=False, to_top_left=False, complete_process_modulations=False)

Run a cypher query against the database and return the resulting SBGN maps.

By default, each record resulting from the query is transformed to zero or more SBGN maps, one for each Map node it contains. The resulting SBGN maps are then returned one by one. Only distinct SBGN maps are returned. When merge_records is set to True, records are merged before being transformed to SBGN maps. When complete is set to True, records are completed before being transformed; a node or a relationship of a record is always completed by all other nodes and relationships that are ultimately necessary to form a valid map from it (see Completion algorithm for more details). Hence if complete is set to True, at least one valid SBGN map will be returned as long as at least one record contains a node or a relationship.

Parameters:

• query (str) – the cypher query

• complete (bool, optional) – if set to True, the nodes and relationships of every record are completed

• merge_records (bool, optional) – if set to True, the records of the result are merged

• to_top_left (bool, optional) – if set to True, each resulting map is moved to the top left of its canvas

• complete_process_modulations (bool) – option to complete processes with the modulations targetting it, default is False

Returns:

the resulting SBGN maps, under the form of a generator. Each returned element is a tuple of the form (map, map_id).

Return type:

Iterator[(`libsbgnpy.libsbgn.map, str)]`

Here is an example:

sbgn_file = "insulin.sbgn"
ston.graph.delete_all()
ston.create_map(sbgn_file, map_id="id1")

# phosphorylation process
query = '''MATCH (process)-[:CONSUMES]->(reactant),
    (process)-[:PRODUCES]->(product),
    (reactant)-[:HAS_STATE_VARIABLE]-(reactant_sv),
    (product)-[:HAS_STATE_VARIABLE]-(product_sv)
    WHERE reactant.label = product.label
    AND reactant_sv.value IS NULL
    AND product_sv.value = "P"
    AND (product_sv.variable IS NULL
        AND reactant_sv.variable IS NULL
        AND product_sv.order = reactant_sv.order
        OR product_sv.variable = reactant_sv.variable)
    RETURN process;'''

# with merge_records set to False
sbgn_maps = ston.query_to_map(query, merge_records=False)
# iterator with three sbgn maps, one for each phosphorylation process of the map
print(sbgn_maps)
for sbgn_map in sbgn_maps:
    print(sbgn_map) # (<id>, <sbgn_map>)

# with merge_records set to False
sbgn_maps = ston.query_to_map(query, merge_records=True)
# iterator with only one sbgn map containing the three phosphorylation processes
print(sbgn_maps)
for sbgn_map in sbgn_maps:
    print(sbgn_map) # (<id>, <sbgn_map>)

query_to_sbgn_file(query, sbgn_file, complete=True, merge_records=True, to_top_left=False, complete_process_modulations=False)

Run a cypher query against the database and write the resulting SBGN maps to one or more SBGN-ML files.

By default, each record resulting from the query is transformed to zero or more SBGN maps, one for each Map node it contains, and each SBGN map is written to a distinct SBGN-ML file. When merge_records is set to True, records are merged before being transformed to SBGN maps. When complete is set to True, records are completed before being transformed; a node or a relationship of a record is always completed by all other nodes and relationships that are ultimately necessary to form a valid map from it (see Completion algorithm for more details). Hence if complete is set to True, at least one valid SBGN map will be written as long as at least one record contains a node or a relationship. If there is only one resulting SBGN map, it is written to sbgn_file. If there are multiple resulting SBGN maps, each distinct SBGN map is written to a different file formatted as follows: the ith distinct SBGN map is written to file <name>-i.<ext> if sbgn_file is of the form <name>.<ext>, and to file sbgn_file-i.sbgn otherwise.

Parameters:

• query (str) – the cypher query

• sbgn_file – the file name where to write the resulting SBGN maps

• complete (bool, optional) – if set to True, the nodes and relationships of every record are completed

• merge_records (bool, optional) – if set to True, the records of the result are merged

• to_top_left (bool, optional) – if set to True, each resulting map is moved to the top left of its canvas

• complete_process_modulations (bool) – option to complete processes with the modulations targetting it, default is False

Returns:

the resulting SBGN-ML file names

Return type:

list[str]

Here is an example:

sbgn_file = "insulin.sbgn"
ston.graph.delete_all()
ston.create_map(sbgn_file, map_id="id1")

# phosphorylation process
query = '''MATCH (process)-[:CONSUMES]->(reactant),
    (process)-[:PRODUCES]->(product),
    (reactant)-[:HAS_STATE_VARIABLE]-(reactant_sv),
    (product)-[:HAS_STATE_VARIABLE]-(product_sv)
    WHERE reactant.label = product.label
    AND reactant_sv.value IS NULL
    AND product_sv.value = "P"
    AND (product_sv.variable IS NULL
        AND reactant_sv.variable IS NULL
        AND product_sv.order = reactant_sv.order
        OR product_sv.variable = reactant_sv.variable)
    RETURN process;'''

# with merge_records set to False
sbgn_files = ston.query_to_map(
    query, "result.sbgn", merge_records=False
)
# three sbgn files are returned, one for each phosphorylation process of the map
print(sbgn_files) # ["result_1.sbgn", "result_2.sbgn", "result_3.sbgn"]

# with merge_records set to False
sbgn_maps = ston.query_to_sbgn_file(
    query, "result.sbgn", merge_records=True
)
# only one sbgn file is returned, containing the three phosphorylation processes
print(sbgn_files) # ["result.sbgn"]