# The Kappy API¶

## Kappa graph handler¶

class kappy.kappa_graph.KappaAgent(typ: str, node_id, sites: dict)

class for representing one kappa agent inside a complex

abc.Sized: len returns its number of sites.

abc.Iterable: iter returns an iterator over the tuple (site_name : str, s : KappaSite)

Use self[site_name] to get a site.

get_neighbours_in_complex(complx)

Destination of the edges.

Parameters: complx (KappaComplex) – Complex self is part of list of KappaAgent

Warning

potential duplicates and self listing.

get_node_id()

::returns: the id of the agent if present (else Null)

get_type() → str

::returns: the type of the agent

class kappy.kappa_graph.KappaComplex(agents)

Class for representing a Kappa connected component

The string representation is the corresponding Kappa code.

abc.Sized: len returns the number of agents in the complex (the size).

abc.Iterable: iter returns an iterator on the agents it contains. Use method items() to get an iterator over the tuples (coordinates,agent).

abc.Container: x in y returns whether the pattern x occurs in y (in term of “Kappa embedding”). Use y.find_pattern(x) to get the embeddings.

Use self[coordinates] to get the agent at coordinates.

agent_ids_by_type()
Returns: a dictionary from type : str to coordinates of agents of type type
agent_ids_of_type(type: str)
Returns: the list of coordinates of agents of type type
find_pattern(ref)
Returns: a list of dictionnary coordinates -> coordinates. Each dictionnary represents an embedding of ref in the complex.
classmethod from_JSONDecoder(data)

Build a KappaComplex from its JSON representation

classmethod from_string(expression)

Build a KappaComplex from its Kappa syntax

items()
Returns: an Iterator where the items are turples (coordinates,agent)
class kappy.kappa_graph.KappaSite(*, links=None, internals=None, future_link=None, future_internal=None)

class for representing one site of a kappa agent (in a complex)

get_internal_state() → str
Returns: if any, the internal state of the site when there can only be 1 by invarient (because it is a pattern/rule/snapshot/…). None if there is not.
Returns: whether the link state is neither free nor unspecified?
neighbours_in_complex(complx)
Returns: the list of KappaAgent connected to here in complx
class kappy.kappa_graph.KappaSnapshot(*, time: float, event: int, complexes: list = [], tokens: dict = {})

class for representing a kappa snapshot

The string representation is the corresponding Kappa code.

complexes

Get the list of complexes.

Returns: a list of pairs (abundance: int, complex : KappaComplex)
event

Get after how many simulation event the snapshot was taken

get_complexes_by_abundance()

Get complexes by abundance. Abundance here means copy number.

Returns: dict abundance -> list_of_complexes_that_abundant
get_complexes_by_size()

Get complexes by size. Size here means the number of agents.

Returns: dict size -> list_of_pair_abundance_complexes_of_that_size
get_largest_complexes()
Returns: list of the largest KappaComplexes with their abundance.
get_least_abundant_complexes()
Returns: list of the least abundant KappaComplexes.
get_most_abundant_complexes()
Returns: list of the most abundant KappaComplexes.
get_size_distribution()
Returns: dict size : int -> number_of_complexes_of_that_size
get_smallest_complexes()
Returns: list of the smallest KappaComplexes with their adundance.
get_token_abundance(token: str) → int

Get the abundance of token

get_total_mass() → int

Get the total number of agents

time

Get the simulation time at which the snapshot was taken

tokens

Get the dictionnary token : str -> abundance : int

exception kappy.kappa_graph.KappaSyntaxError

## Utilities for interaction with tools¶

Shared functions of api client for the kappa programming language

class kappy.kappa_common.SimulationParameter(plot_period: float, pause_condition: str, seed: int = None, store_trace: bool = False)

Parameters needed to run a simulation

Parameters: plot_period – How often values of observables should be computed during the simulation pause_condition – (a boolean kappa expression) When the simulation will stop itself and wait for further actions. seed – specify the seed of the random number generator used by the simulator store_trace – Because simulation traces become huge, you must specify before starting a simulation whether you may query it later
class kappy.kappa_common.PlotLimit(offset=None, points=None)

Parameters of plot query

Parameters: points – maximum number of column that the reply should contains. (None means unlimited) offset – At what column number the reply should start (None means return the end of the simulation)
exception kappy.kappa_common.KappaError(errors)

Error returned from the Kappa server

## Kappa tool driver¶

Client for the kappa programming language through standard channel api

class kappy.kappa_std.KappaStd(kappa_bin_path=None, delimiter='x1e', args=None)

Kappa tools driver run locally.

kappa_bin_path – where to find kappa executables
(None means use the binaries bundled in the package)
delimiter – What to use to delimit messages (must not appears in
message body default ‘x1e’)

args – arguments to pass to kappa executables

add_model_file(model_fpath, position=1, file_id=None)

Add a kappa model from a file at given path to the project.

add_model_string(model_str, position=1, file_id=None)

Add a kappa model given in a string to the project.

analyses_constraints_list()

Returns a bunch of invarients on the last parsed model

analyses_contact_map(accuracy=None)

Returns the contact of the last parsed model

Parameters: accuracy (str) – “high” means take into account reachability from initial state. “low” means don’t.
analyses_dead_rules()

Returns the dead rules of the last parsed model

analyses_influence_map(accuracy=None)

Returns the influence_map of the last parsed model

Parameters: accuracy (str) – level can be “low”, “medium”, “high” or “full”. Default is medium.
analyses_potential_polymers(accuracy_cm='high', accuracy_scc='high')

Returns the list of potential polymers of the last parsed model

file_create(file_)

Add a file to the project

Parameters: file_object – a Kappa_common.File
file_delete(file_id)

Remove a file from the project

file_get(file_id)

Returns file file_id stored in the project

file_info()

Lists the files of the project (returns a FileMetadata array)

get_default_sim_param()

Get the default SimulationParameter instance.

get_is_sim_running()

Check if the current simulation is running.

project_overwrite(ast, file_id='model.ka')

Overwrite the project with the given AST

Parameters: ast – the ast in the format returned by project_parse file_id (str) – a virtual file name in which the ast will be dump
project_parse(sharing_level='compatible_patterns', **kwargs)

Parses the project

Parameters: kwargs – list of algebraic variables to overwrite Each element has the form variable_name=numerical_val
set_default_sim_param(*args, **kwargs)

Set the simulation default simulation parameters.

You can pass one of two things in as input: - a kappa_common.SimulationParameter instance - the arguments and keyword argument to create such an instance.

The parameters you specify will be used by default in simulations run by this client.

shutdown()

Shut down kappa instance.

Given a key to a kappa service shutdown a running kappa instance.

simulation_DIN(DIN_id)

Returns a given generated DIN

simulation_DINs()

Lists DIN generated during the simulation

simulation_continue(pause_condition)

Restarts a paused simulation

simulation_delete()

Deletes running/paused simulation

simulation_file_line(file_line_id)

Returns the file file_line_id generated by $PRINT interventions simulation_info() Returns state and progress of the simulation simulation_info_file_line() Lists files generated by$PRINT during the simulation

simulation_intervention(intervention_code)

Fires a intervention in a paused simulation

simulation_log_messages()

Returns simulation log

simulation_pause()

Pauses a simulation

simulation_plot(limit=None)

Returns the plot data of the simulation

Note: No actual plot is produced as a result of this function call.

Parameters: limit – optionnal boundaries to only get a subplot format – { offset : 100, nb_points : 500 } returns the last points if offset is Null simulation_results – a json containing the data from the simulation.
simulation_snapshot(snapshot_id)

Returns a given generated snapshot

simulation_snapshots()

Lists snapshots generated during the simulation

simulation_start(simulation_parameter=None)

Start the simulation from the last parsed model.

Parameters: simulation_parameter – a kappa_common.SimulationParameter instance. The default is set using the set_default_sim_param method.
wait_for_simulation_stop(timeout=None)

Block until the simulation is done or timeout seconds exceeded.

If the simulation stops before timeout, siminfo is returned.