Cyclone

Home | Architecture - Requirements - Installation - Tutorial - FAQ - | Sourceforge Project | References - About Us

Introduction
The following tutorial page will explain you how to deal with Cyclone with more efficiency. We begin with a guided tour of Cyclone Platform. Next we describe the procedure to create your own instance of Cyclone (from XSD, XML generation to PGDB loading). Then we explain how to query your favorite PGDB (Java HQL and Criteria API). Then we detail the procedure to edit PGDBs and save them to BioCyc. Finally we focus on the export and visualisation of biological network (Jung, Cytoscape).

Index
- Cyclone Platform Guided Tour >
- Creating the CycloneML Schema >
- Creating a CycloneML instance >
- Loading a PGDB>
- Querying a PGDB >
- Editing a PGDB >
- Saving Cyclone Data into BioCyc >

A full page is dedicated to graph application with Cyclone, see graphs page

Cyclone Platform Guided Tour < | >

Cyclone Platform is a pre-configured version of Cyclone Core. It is bundled with JBoss Eclipse IDE for Linux platform. The installation procedure is described at Cyclone Platform Installation.
This first tutorial briefly explores the panels of Cyclone Platform.
Flash tutorial


Creating the CycloneML Schema < | >

Extracting and mapping the BioCyc ontology onto XML schema will allow you to build the Cyclone model.
The following java code is extracted from the Tutorial.java included in the Cyclone distribution.

    int max = 10;  //between 1 (save only one instance of each type - for quick test ) and 100000000 (to unlimit the number of instance ) 
    String orgid = new String("Ecoli");//Your Favorite Pathway Genome Database - PGDB id
    /**
     * Example 1
     * Extract the xml schema as ./Cyclone_Core/schema/Ecoli.xsd  
     * Pathway Tools is required
     */
    public static String TutorialEx1(String myOrganism, int max) {
        String[] organisms = new String[1];
        organisms[0]=myOrganism;
        return Biocyc2Xsd.createXsd(organisms,max);
    }
    TutorialEx1(orgid,max);
Below is an extract of the resulting schema for EcoCyc 10.5 (You can download the whole file CycloneBC96.xsd).
<?xml version="1.0" encoding="UTF-8"?>

<!-- CycloneXSD . This file may be freely distributed and modified under the terms of the CeCILL  Licence. It should be
distributed with the file. If you do  not have a copy, see: http://www.cecill.info/index.en.html -->
<!-- For more information on the Cyclone project and its  aims, or to join the cyclone mailing list, visit the home page at:  
http://www.genoscope.cns.fr/bioinfo/nemo . 
Cyclone is a java project created at Genoscope,  French National Sequencing Center - CNRS UMR 8030. -->
<!-- Director: Jean WEISSENBACH -->
<!-- Bioinformatic Director:  Vincent SCHACHTER -->
<!-- Copyright for this file is held jointly by the individual creators. -->
<!-- Francois LE FEVRE (flefevre@genoscope.cns.fr) -  Network Modeling team (NeMo), http://www.genoscope.cns.fr/bioinfo/nemo -->
<!-- Serge SMIDTAS (sergi@sergi5.com) - Network Modeling  team (NeMo) - http://www.genoscope.cns.fr/bioinfo/nemo -->
<!-- and by the following individual authors. -->

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:hj="http://hyperjaxb2.jvnet.org/customizations" xmlns:jaxb="
http://java.sun.com/xml/ns/jaxb" xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc" jaxb:extensionBindingPrefixes="hj xjc" jaxb:version="1.0">
  <xs:element name="BioCyc">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="Ccid" type="xs:string" minOccurs="0" maxOccurs="1">
          <xs:annotation>
            <xs:appinfo>
              <hj:id>
                <hj:generator generatorClass="uuid"/>
              </hj:id>
            </xs:appinfo>
          </xs:annotation>
        </xs:element>
        <xs:element name="PgdbId" type="xs:string" minOccurs="1" maxOccurs="1"/>
        <xs:element name="Level" type="xs:int" minOccurs="0" maxOccurs="1"/>
        <xs:element name="Version" type="xs:int" minOccurs="0" maxOccurs="1"/>
        <xs:element name="AnatomicalStructures" type="AnatomicalStructures" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element name="Cco" type="Cco" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element name="Chemicals" type="Chemicals" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element name="Databasess" type="Databasess" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element name="EnzymaticReactions" type="EnzymaticReactions" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element name="Evidences" type="Evidences" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element name="GeneralizedReactions" type="GeneralizedReactions" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element name="Kbdescriptor" type="Kbdescriptor" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element name="Notes" type="Notes" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element name="Organisms" type="Organisms" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element name="ParalogousGeneGroups" type="ParalogousGeneGroups" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element name="People" type="People" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element name="PolymerSegments" type="PolymerSegments" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element name="ProteinFeatures" type="ProteinFeatures" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element name="Publications" type="Publications" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:complexType name="AnatomicalStructures">
    <xs:sequence>
      <xs:element name="Ccid" type="xs:string" minOccurs="0" maxOccurs="1">
        <xs:annotation>
          <xs:appinfo>
            <hj:id>
              <hj:generator generatorClass="uuid"/>
            </hj:id>
          </xs:appinfo>
        </xs:annotation>
      </xs:element>
      <xs:element name="FrameId" type="xs:string"/>
      <xs:element name="Organism" type="xs:string"/>
      <xs:element name="FrameType" type="xs:string"/>
      <xs:element name="Comment" type="Comment" minOccurs="0" maxOccurs="unbounded">
        <xs:annotation>
          <xs:appinfo>
            <jaxb:property>
              <jaxb:javadoc>The Comment slot stores a general comment about the object that contains the slot.</jaxb:javadoc>
            </jaxb:property>
          </xs:appinfo>
        </xs:annotation>
      </xs:element>
      <xs:element name="CommentInternal" type="CommentInternal" minOccurs="0" maxOccurs="unbounded">
        <xs:annotation>
          <xs:appinfo>
            <jaxb:property>
              <jaxb:javadoc>A comment for internal purposes that is not released to the pubilc.</jaxb:javadoc>
            </jaxb:property>
          </xs:appinfo>
        </xs:annotation>
      </xs:element>
      <xs:element name="CommonName" type="CommonName" minOccurs="0" maxOccurs="unbounded">
        <xs:annotation>
          <xs:appinfo>
            <jaxb:property>
              <jaxb:javadoc>The primary name by which an object is known to scientists -- a widely 
              used and familiar name in some cases arbitrary choices must be made .</jaxb:javadoc>
            </jaxb:property>
          </xs:appinfo>
        </xs:annotation>
      </xs:element>
      <xs:element name="ComponentOf" type="ComponentOf" minOccurs="0" maxOccurs="unbounded">
        <xs:annotation>
          <xs:appinfo>
            <jaxb:property>
              <jaxb:javadoc>This slot specifies an object that contains this object as a smaller part. 
              For example, this slot points from a monomer to a larger complex that contains it.</jaxb:javadoc>
            </jaxb:property>
          </xs:appinfo>
        </xs:annotation>
      </xs:element>
      <xs:element name="Components" type="Components" minOccurs="0" maxOccurs="unbounded">
        <xs:annotation>
          <xs:appinfo>
            <jaxb:property>
              <jaxb:javadoc>This slot lists the components of some physical assembly, such as the 
              subunits of a protein complex or the genes within a chromosome. The coefficient of each component when known is listed
              as an annotation of the component value under the label coefficient. When a modified protein is created to reflect a 
              chemically modified alternate form of the protein, if that protein is a complex, its subunit structure need not be
              mirrored in the modified-protein frame. The subunit structure should be defined only once, for the frame that
              represents the unmodified form of the protein.</jaxb:javadoc>
            </jaxb:property>
          </xs:appinfo>
        </xs:annotation>
      </xs:element>
      <xs:element name="CreationDate" type="CreationDate" minOccurs="0" maxOccurs="unbounded">
        <xs:annotation>

This file ( Package explorer> schema/biocyc.xsd ) can be opened and browsed with Eclipse as shown below. Switch beteween the Source and the Graph view. the view


Creating a CycloneML instance < | >
Any object (Compounds, Proteins, Genes, Reaction, Pathway ...) or set of objects can be exported into CycloneML, all the way to an entire PGDB.
    /**
     * Example 2
     * Extract a Pathway Genome DataBase (PGDB - a Cyc) into a CycloneML file as ./Cyclone_Core/Data/Pgdb/CycloneML/ 
     * Pathway Tools is required
     */
    public static String TutorialEx2(String myOrganism,int max) {
        return Biocyc2Xml.createXml(myOrganism,max);
    }

     TutorialEx2("Ecoli",10000);

Below is an example of the CycloneML output file of a PGDB 10.5 (You can download the whole file for Pseudomonas a. CycloneML or an extract file for Escherichia coli extract ).
<?xml version="1.0" encoding="UTF-8"?>
<BioCyc xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:noNamespaceSchemaLocation="http://nemo-cyclone.sourceforge.net/CycloneBC96.xsd">

<!-- CycloneXSD . This file may be freely distributed and modified under the terms of the CeCILL  Licence.
It should be distributed with the file. If you do  not have a copy, see: http://www.cecill.info/index.en.html -->
<!-- For more information on the Cyclone project and its  aims, or to join the cyclone mailing list, visit the home page at: 
http://www.genoscope.cns.fr/bioinfo/nemo . Cyclone is a java project created at Genoscope,  French National Sequencing Center - CNRS UMR 8030. -->
<!-- Director: Jean WEISSENBACH -->
<!-- Bioinformatic Director:  Vincent SCHACHTER -->
<!-- Copyright for this file is held jointly by the individual creators. -->
<!-- Francois LE FEVRE (flefevre@genoscope.cns.fr) -  Network Modeling team (NeMo), http://www.genoscope.cns.fr/bioinfo/nemo -->
<!-- Serge SMIDTAS (sergi@sergi5.com) - Network Modeling  team (NeMo) - http://www.genoscope.cns.fr/bioinfo/nemo -->
<!-- and by the individual following authors. -->

  <PgdbId>Ecoli1142257131369</PgdbId>
  <Level>1</Level>
  <Version>1</Version>
  <AnatomicalStructures>
    <FrameId>|Compartments|</FrameId>

    <Organism>Ecoli</Organism>
    <FrameType>class</FrameType>
    <Comment>
      <Value>"This class describes cellular compartments such as the cytoplasm. A given 
      compartment can be a component of a membrane, e.g., the cytoplasm is a component of the cytoplasmic membrane in the
      sense that it is bounded by the cytoplasmic membrane."</Value>
    </Comment>
    <CreationDate>
      <Value>3243104644</Value>

    </CreationDate>
    <Creator>
      <Value>|pkarp|</Value>
    </Creator>
    <Instances>
      <Value>|Anatomical-Structures|</Value>
      <Parents>false</Parents>
    </Instances>
    <Schema>
      <Value>T</Value>
    </Schema>
  </AnatomicalStructures>
  <AnatomicalStructures>
    <FrameId>|Membranes|</FrameId>
    <Organism>Ecoli</Organism>

    <FrameType>class</FrameType>
    <Comment>
      <Value>"This class describes cellular membranes such as the cytoplasmic membrane. 
      A membrane can be a Component-Of a compartment that contains it, for example, in bacteria, the cytoplasmic membrane
      would be a Component-Of the periplasm."</Value>
    </Comment>
    <CreationDate>
      <Value>3243104644</Value>
    </CreationDate>

    <Creator>
      <Value>|pkarp|</Value>
    </Creator>
    <Instances>
      <Value>|Anatomical-Structures|</Value>
      <Parents>false</Parents>
    </Instances>

    <Schema>
      <Value>T</Value>
    </Schema>
  </AnatomicalStructures>
  <Cco>
    <FrameId>CCO-CELLWALL</FrameId>
    <Organism>Ecoli</Organism>

    <FrameType>class</FrameType>
    <CommonName>
      <Value>"cell wall"</Value>
    </CommonName>
    <CreationDate>
      <Value>3330884039</Value>
    </CreationDate>

    <Creator>
      <Value>|paley|</Value>
    </Creator>
    <Definition>
      <Value>"The rigid or semi-rigid envelope lying outside the cell membrane of plant, fungal, and 
      most prokaryotic cells, maintaining their shape and protecting them from osmotic lysis. In plants it is made of cellulose and, 
      often, lignin; in fungi it is composed largely of polysaccharides; in bacteria it is composed of peptidoglycan."</Value>
    </Definition>
    <DefinitionReference>
      <Value>"Gene Ontology Consortium"</Value>

    </DefinitionReference>
    <Goid>
      <Value>"GO:0005618"</Value>
    </Goid>
    <Instances>
      <Value>CCO</Value>
      <Parents>true</Parents>

    </Instances>
    <Instances>
      <Value>CCO-SURFACE-MAT</Value>
      <Parents>false</Parents>
    </Instances>
    <Schema>
      <Value>T</Value>

    </Schema>
    <Sensu>
      <Value>|Organisms|</Value>
    </Sensu>
  </Cco>
This file (Package explorer > samples/ can be browsed using Eclipse as shown below:



Loading a PGDB < | >
After the CycloneML file has been generated for your favorite organism, Cyclone will load these data and make them persistent in your favorite RDMBs.
    /**
     * Example 3
     * Load a cycloneML file into the Cyclone database 
     * mySQL is required
     */
    public static void TutorialEx3(String myPath) {
        Xml2CycloneDb.importXml(myPath);
    }

    TutorialEx3("./Cyclone_Core/Data/Pgdb/CycloneML/Ecoli.xml");
A flash tutorial illustrates this step. Flash Tutorial

Querying a PGDB < | >
It is easy to query your organism directly in HQL in Eclipse as shown below:



A Flash tutorial illustrates this step:
Flash Tutorial

It is also possible to write HQL queries in Java programs as illustrated below:
    /**
     * Example 4a
     * Query Cyclone using Object Query Language or Criteria API
     * Find all enzymes for which ATP is an inhibitor with OBJECT QUERY LANGUAGE
     * mySQL is required
     * This function was inspired by Karp et al. 2004, Application Note in Bioinformatics
     */
    public static List TutorialEx4a(String myOrganism, String metabolite) {
        //Open a session
        GeneralServices.EasyCycloneOpenOrganism(myOrganism);
        
        //HQL
        Query hql = GeneralServices.myEasySession.createQuery(
                "select er.FrameId from EnzymaticReactions er "+ 
                "where er.Organism = :orgid "+ 
        "  and er.InhibitorsAll.Value like :metabolite");
        //Replace variable in hql
        hql.setString("orgid",myOrganism);
        hql.setString("metabolite","ATP");
        
        //Retrieves results
        List myResults =hql.list();
        System.out.println(myResults);
        
        GeneralServices.EasyCycloneClose();
        
        return myResults; 
    }
A third method exists to query database, using the Criteria API:

    /**
     * Example 4b
     * Query Cyclone using Object Query Language or Criteria API
     * Find all enzymes for which ATP is an inhibitor with CRITERIA API
     * mySQL is required
     */
    public static void TutorialEx4b(String myOrganism) {
        //Open session
        GeneralServices.EasyCycloneOpenOrganism(myOrganism);
        
        
        try
        {
            //Create an instance of the enzymatic reaction
            ObjectFactory myFactory = new ObjectFactory();
            EnzymaticReactions er;
            er = myFactory.createEnzymaticReactions();
            er.setOrganism("Ecoli");
            
            //Create a criteria
            List results = GeneralServices.myEasySession.createCriteria(EnzymaticReactions.class)
            .add(Example.create(er))
            .createCriteria("InhibitorsAll")
            .add(Restrictions.like("Value","ATP"))
            .list();
            
            //Display results
            //Becareful we extract all the object, so we get an java adress
            System.out.println(results);
            
            //Display an attribute of the results
            int i=0;
            for(EnzymaticReactions myER : results){
                System.out.println(myER.getFrameId());
                i++;
            }
        } catch (JAXBException e)
        {
            e.printStackTrace();
        }
        //Close the session
        GeneralServices.EasyCycloneClose();	
    }	

Editing a PGDB < | >
Cyclone data can be edited through the edition of the exported XML file using Jaxfront. First export data into CycloneML:
    /**
     * Example 7
     * Extract data from Cyclone to CycloneML 
     * mySQL is required
     */ 
    public static String TutorialEx7(String myOrganism) {
        String keySession = new String("cyclone");
        BiocycDao myBiocycDao = new BiocycDao(keySession);
        BioCyc myBiocyc = myBiocycDao.getByOrgid(myOrganism);  
        Session mySession = HibernateUtil.getSessionFactory(keySession).openSession();
        mySession.lock(myBiocyc,LockMode.READ);
        return ExportCyclone2Xml.exportBiocyc( myBiocyc, "Data/Pgdb/CycloneML/"+myOrganism+".export.xml");
    }
Then, open the file using Jaxfront to graphicaly edit data:



Java code can be used also to update data.
    /** 
     * Example 6
     * Edit a PGDB 
     * we correct a reaction stoechiometry of Ecoli_v9.5
     * by adding a reactant to the 6PGLUCONDEHYDROG-ENZRXN reaction.
     * mySQL is required
     */
    public static void TutorialEx6(String myOrganism, String myEnzymaticReactionFrameId, int max) {      
        //String myEnzymaticReactionFrameId ="6PGLUCONDEHYDROG-ENZRXN";
        try
        {
            GeneralServices.EasyCycloneOpenOrganism(myOrganism);
            
            EnzymaticReactionsDao myERDao = new EnzymaticReactionsDao("cyclone");
            EnzymaticReactions myER = (EnzymaticReactions)myERDao.getObjectByFrameandOrganism(myOrganism,myEnzymaticReactionFrameId);
            
            GeneralServices.myEasySession.lock(myER,LockMode.READ);
            
            // get the Generalized Reaction corresponding to the Enzymatic reaction 6PGLUCONDEHYDROG-ENZRXN
            String reactionFrameId = ((Reaction)(myER.getReaction().get(0))).getValue();
            GeneralizedReactionsDao myRDao = new GeneralizedReactionsDao("cyclone");
            GeneralizedReactions myReaction = (GeneralizedReactions)myRDao.getObjectByFrameandOrganism(myOrganism,reactionFrameId);
            
            // build the proton object
            ObjectFactory factory = new ObjectFactory();
            Rightt protonParticipant = factory.createRightt();
            protonParticipant.setValue("PROTON");
            protonParticipant.setCoefficient("1");
            
            // Add the proton to the reaction
            myReaction.getRightt().add(protonParticipant); 
            // Save the modified reaction
            myRDao.store(myReaction);
          
            // Now we should add the reverse link to be coherent with the BioCyc schema. (this is optional)
            // We add the reaction to the list of reactions in which 'proton' appears.
            {
                // We get the Proton object of the database
                ChemicalsDao cDao = new ChemicalsDao("cyclone");
                Chemicals proton  = (Chemicals)cDao.getObjectByFrameandOrganism(myOrganism,"PROTON");
                // We get the AppearsInRightSideOf object
                AppearsInRightSideOf myRxn = factory.createAppearsInRightSideOf();
                // We add the link and save
                myRxn.setValue(reactionFrameId);
                proton.getAppearsInRightSideOf().add(myRxn);
                cDao.store(proton);
            }
            
            GeneralServices.EasyCycloneClose();
        } catch (JAXBException e)
        {
            e.printStackTrace();
        }
    }
This is a second example:
    /** 
     * Example9
     * Add information to your favorite PGDB from a file automatically.
     * This example should require investment from yourself. A list of orthologs between your
     * organism and Ecoli is required. The file format of the file is:
     * EGCCOLIID=YOURORGANISMID
     */ 
     public static void TutorialEx9(String orgIdCyclone, String orgIdBiocyc) {
        String keySession = new String("cyclone");
        int max = 2;
        BiocycDao myBiocycDao = new BiocycDao(keySession);
        BioCyc myBiocyc = myBiocycDao.getByOrgid(orgIdCyclone);

        // If you have a list of orthologs links between Ecoli and your new
        // organism
        OrthologLinks2Cyclone.addOrthologsLinks(myBiocyc, keySession, "Ecoli", "Data/Homology/ecocyc.bbh.organisms.txt", max);
     }

Saving Cyclone Data into BioCyc < |
All changes made to your organism can be commited back into BioCyc.
    /**
     * Example 8
     * Save an organism with the into BioCyc
     * BE CAREFULL it will override your organism. Use this function with caution. 
     You should BACKUP YOUR ORGANISM BEFORE .
     * mySQL and pathway tools are required
     */ 
    public static void TutorialEx7(String orgIdCyclone, String orgIdBiocyc) {
        String keySession = new String("cyclone");
        //int max = 2;
        BiocycDao myBiocycDao = new BiocycDao(keySession);
        BioCyc myBiocyc = myBiocycDao.getByOrgid(orgIdCyclone);
        
        //If you have a list of orthologs links between Ecoli and your new organism
        //OrthologLinks2Cyclone.addOrthologsLinks(myBiocyc,keySession,
        "Ecoli","Data/Homology/ecocyc.bbh.acineto2.txt",max);
        
        ExportCyclone2Biocyc myExportBiocycJava = new ExportCyclone2Biocyc(keySession,orgIdCyclone, orgIdBiocyc);
        myExportBiocycJava.processCyclonePgdb2BiocycPgdb();	
    }

Graphs and Cyclone
A full page is dedicated to graph application with Cyclone, see graphs page


Home | Architecture - Requirements - Installation - Tutorial - FAQ - | Sourceforge Project | References - About Us

Genoscope SourceForge.net Logo © 2004-2006 Cyclone. All trademarks are the properties of their respective owners.
CPS is copyright by Serge Smidtas and Francois Le Fevre