CyniAlgorithmTutorialSwingUI

#How to create a Cyni Algorithm with own Java Swing UI

##Introduction

In order to help app developers, we provide a Cyni Algorithm sample, which contains a "HelloWorld" implementation of a Cyni Algorithm. This sample will serve as a starting point or template for new app developers. Cyni sample code can be used by following these steps:

1. Check out the cyni sample projects from our Github repository with this command:

git clone git://github.com/schwikowskilab/cyni-samples.git

1. Go the cyni-gui-algo-sample directory and compile it with mvn clean install

This tutorial is focused on showing the main steps to create a Cyni Algorithm that does not use Cytoscape Tunables to generate the User Interface for input parameter handling. All the User Interface methods are centralized in the new class extending CyniAlgorithmContext. Next sections describe each file that needs to be created to produce a Cyni Algorithm App that provides your own swing UI.

##Pom File Here are the main lines to modify in the pom.xml file. The fields bundle.symbolicName and bundle.namespace properties should be modified according to new app directory configuration. Tags groupId and artifactId also have to be modified. Finally, version tab should set to developer requirements.

<properties>
	<bundle.symbolicName>cyni-gui-algo-sample</bundle.symbolicName>
	<bundle.namespace>fr.systemsbiology.cyniSampleGuiAlgorithm.internal</bundle.namespace>
	<cytoscape.api.version>3.1.0</cytoscape.api.version>
	<cyni.api.version>1.0.0</cyni.api.version>
	<maven-bundle-plugin.version>2.3.4</maven-bundle-plugin.version>
	<osgi.api.version>4.2.0</osgi.api.version>
</properties>

<groupId>fr.systemsbiology.cyniSampleGuiAlgorithm</groupId>
<artifactId>cyniSampleGuiAlgorithm</artifactId>
<packaging>bundle</packaging>
<name>${bundle.symbolicName}</name>

<version>3.0.0-alpha1-SNAPSHOT</version>

##CyActivator In this file, any Cyni Algorithm implemented needs to be registered. These two lines do the work. First, we create the object for the new Cyni Algorithm and then we register it to make it available by the Cyni Algorithm Manager.

    //Define new Cyni Algorithm
    CyniSampleGuiAlgorithm test = new CyniSampleGuiAlgorithm();
    //Register new Cyni Algorithm
    registerService(bc,test,CyCyniAlgorithm.class, new Properties());

##CyniSampleAlgorithm In the constructor of this class, there are three parameters that need to be set. The computer name of the algorithm, the human name of the algorithm (the one used to be displayed) and the category of the algorithm. This parameters are passed to the parent class.

public CyniSampleAlgorithm() {
    super("sampleGuiAlgo.cyni","Cyni Sample Gui Algorithm",true,CyniCategory.INDUCTION);
}

The other two main functions serve to generate the task object and the context object. The context method contains a tunableSetter argument, which allows users to set the context without using a User Interface. The content of context method should be unmodified regarding the lines involving the tunableSetter.

public TaskIterator createTaskIterator(Object context,CyTable table, CyNetworkFactory networkFactory, CyNetworkViewFactory networkViewFactory,CyNetworkManager networkManager,CyNetworkTableManager netTableMgr, CyRootNetworkManager rootNetMgr,CyNetworkViewManager networkViewManager, CyLayoutAlgorithmManager layoutManager, CyCyniMetricsManager metricsManager) {
    selectedTable = table;
    return new TaskIterator(new CyniSampleGuiAlgorithmTask(getName(),(CyniSampleAlgorithmContext)context,networkFactory,networkViewFactory,networkManager,netTableMgr,rootNetMgr,networkViewManager,layoutManager,metricsManager, selectedTable));
        }

public Object createCyniContext(CyTable table, CyCyniMetricsManager metricsManager, TunableSetter tunableSetter,Map<String, Object> mparams) {
    Object context;
    selectedTable = table;
    context = new CyniSampleGuiAlgorithmContext();
    if(mparams != null && !mparams.isEmpty())
        tunableSetter.applyTunables(context, mparams);
    return context;
}

##CyniSampleAlgorithmContext

This file must extend the CyniAlgorithmContext class. If we don't want Cytoscape to use Cytoscape Tunables to display the User Interface that will allow selecting the parameters for this algorithm. This class should modify the following methods to provide to Cytoscape your own java swing panel for parameter handling.

public boolean contextHasOwnSwingPanel()
{
	return true;
}

public JPanel getContextSwingPanel()
{
	return mainPanel;
}
	
public boolean contextContentValid()
{
	if(getParam2() > 0)
		return true;
	else
		return false;
}

The method contextContentValid only needs to be implemented if the value of input parameters need to be validated before applying the algorithm. This method will be called before running the algorithm task and the task will only continue if this method returns true. The values entered in the UI needs to be retrieved later on, so this class should provide methods to get the final values for these parameters. In Cyni sample, we provide (below) an example of these kind of methods.

public double getParam1()
{
	return param1Panel.getLimit();
}

public double getParam2()
{
	return param2Panel.getLimit();
}

There are three other files in this Cyni Sample that basically contain all implementation to generate the desired Swing Panel. This is just a possibility but any kind of implementation could be correct provided a Java Swing panel is finally generated.

##CyniSampleAlgorithmTask This file contains the actual implementation of the Cyni Algorithm. In the constructor, the context and the selected table are passed. In the context, there is the information of each input parameter for the algorithm. Any implementation related to the Cyni Algorithm needs to be developed in the doCyniTask method.

public CyniSampleGuiAlgorithmTask(final String name, final CyniSampleAlgorithmContext context, CyNetworkFactory networkFactory, CyNetworkViewFactory networkViewFactory,CyNetworkManager networkManager,CyNetworkTableManager netTableMgr, CyRootNetworkManager rootNetMgr,CyNetworkViewManager networkViewManager,CyLayoutAlgorithmManager layoutManager, CyCyniMetricsManager metricsManager, CyTable selectedTable)
{
    super(name, context, networkFactory, networkViewFactory, networkManager, networkViewManager, netTableMgr, rootNetMgr);
    this.param1 = context.getParam1();
    this.param2 = context.getParam2();
    this.mytable = selectedTable;

}

/**
 *  Perform actualtask.
*/
@Override
final protected void doCyniTask(final TaskMonitor taskMonitor) {

    Double progress = 0.0d;
    CyNetwork networkSelected = null;
    String networkName;
    CyLayoutAlgorithm layout;
    CyNetworkView newNetworkView ;

    taskMonitor.setStatusMessage("Algorithm running ...");
    taskMonitor.setProgress(progress);

    .......................

    taskMonitor.setProgress(1.0d);
}

The core of the method doCyniTask contains the main steps to create the new network. As shown in the code below, first a new network is created and then the selected table is checked to see if it is associated to a Cytoscape network. After that, if needed, a Cyni Table can be created to help better working with Cytoscape Table Data. Finally, the new created network needs to be displayed and a layout is applied to the network. Several functions have been developed to help to perform all these tasks.

//Create new network
CyNetwork newNetwork = netFactory.createNetwork();
		
		
//Check if a network is associated to the selected table
networkSelected = getNetworkAssociatedToTable(mytable);
		
// Create the CyniTable
CyniTable data = new CyniTable(mytable,attributeArray.toArray(new String[0]), false, false, selectedOnly);
		
		
//Set the name of the network, another name could be chosen
networkName = "Induction " + newNetwork.getSUID();
if (newNetwork != null && networkName != null) {
    CyRow netRow = newNetwork.getRow(newNetwork);
    netRow.set(CyNetwork.NAME, networkName);
}
		
		
/*****************************************************/
//
// Add the different nodes and edges according to the table data
//
//
/*****************************************************/
		
//Display the new network
if (!cancelled)
{
    newNetworkView = displayNewNetwork(newNetwork, false);
    taskMonitor.setProgress(1.0d);
    layout = layoutManager.getDefaultLayout();
    Object context = layout.getDefaultLayoutContext();
    insertTasksAfterCurrentTask(layout.createTaskIterator(newNetworkView, context,     CyLayoutAlgorithm.ALL_NODE_VIEWS,"");
}

Finally, there are two actions that will be performed very often when working with tables and networks and it is important to know how to do it.

####How to get data associated to a node or edge

There are two possibilities to perform this action.

1. First, get the table and then use ''getRow'' method.

CyTable table = network.getTable(CyNode.class,CyNetwork.DEFAULT_ATTRS);
CyRow nodeRow = table.getRow(node.getSUID());

2. You can also go straight into getting the row without having to get the table by using the ''getRow'' method in the !CyNetwork class.

CyRow nodeRow = cyNetwork.getRow(node,CyNetwork.DEFAULT_ATTRS);

####How to get a node or an edge associated to a row in a table data

You need to get the SUID value for that row and then use it as input paramter in the ''getNode'' method.

CyNode node = network.getNode(row.get(CyIdentifiable.SUID, Long.class));