pyNetConv - Network Conversion Tool


%!includeconf: config.t2t

%!preproc: _NX_ [NetworkX http://networkx.sourceforge.net]

== News ==

: **2005-08-30** (v0.12)
  - new features and fixes. See [changelog changelog.html]

: **2005-08-22** (v0.11.2)
  - bugfix in pajek module

: **2005-08-19**
  - Windows installer added to the download section.

: **2005-08-16** (v0.11)
  - improvments in pajek filter see [changelog changelog.html]
  - gui is now istalled in the system path on *nix (Linux, FreeBSD, etc.) and on Python scripts folder on Windows (using distutils)

: **2005-07-21** (v0.10.2)
  - bug fix in netconv.pajek

: **2005-07-21** (v0.10.1)
  - Added support to export all nodes in NX format. Now supports conversion to
  NX of networks with isolated (unconnected) nodes.
  - new function added: ``netconv2NX()`` to make the conversion to NX easier. 
  See [NX #NX].
  - API back to the source download (I forgot it in 0.10)

: **2005-07-13** (v0.10)
  Now using distutils. See [installation instructions #install].

: **2005-07-08** (v0.9)
  Functions to import/export network as a list added. With this, it is
  possible to use some other tools to graph manipulation such as the great
  _NX_. See [this section #NX]
  for more details.

: **2005-05-20** (v0.8.1)
  See [changelog changelog.html] for changes
  
: **2005-04-25** (v0.8)
  Support for expression data added.

: **2005-04-19** (v0.7)
  GUI added! See [screenshots #screenshots]

: **2005-04-13** (v0.6)
  Files uploaded to the [project page PRJ_PAGE]



== What is pyNetConv? ==

PNC is a Python library created to help the conversion of some 
network file formats.

Since version 0.6, PNC is capable to read/write (and convert from/to)
the following file formats:

- Pajek network files (.net)
- Pajek cluster files (.clu)
- Cytoscape network files (.sif)
- Cytoscape node attributes files
- GML files


And from version 0.8 it is able to import tab-separated values exported by
Affymetrix Micro Array Suite 5.0 (MAS5) and export this data as Cytoscape
node attributes or expression data (.pval file).

PNC is a library to create a software that is able to read/write
networks in the formats supported by PNC. If all you want is convert the
files without the need create a program, then the Graphical user interface is
for you. See the [screenshots session #screenshots] to see how the GUI looks
like.



== Motivation ==

The motivation for creating this tool was that there are many good graph
visualization/layout tools available (each one with strengths in some areas)
but sometimes they have incompatible file formats (this is true for PAJEK and
CYTOSCAPE). Some tools can read/write GML files, while other not.

So with PNC we plan to fill this gap allowing the user to exchange
files between this tools and use the best features of each tool to generate
the final graph.



== How it works ==

PNC is developed as a library, so one can write his own code and use
PNC to import/export the network in the formats supported.

Example:

```
n = Network()
importPajek(n, 'network.net')
importPajekClu(n, 'network.clu')
n.cluster2Attributes()
n.pajek2pos(1000)
exportCyAttributes(n, 'network.cluster')
exportGML(n, 'network.gml') # network + cluster information
```



=== Using NX ===[NX]

If you want to import a GML, Pajek or SIF file to use with _NX_, you can 
do the following:

```
import netconv
import networkx as NX

n = netconv.Network()
netconv.importPajek(n, 'network.net')

G = NX.Graph()
netconv.netconv2NX(n,G)

# from here, work with G
```


== Documentation ==

Documentation is on plans. For now you can take a look at the 
[pyNetConv API api/] for some documentation.



== Screenshots ==[screenshots]

 | [images/pynetconv1.png]
 | [images/pynetconv2.png]
 | [images/pynetconv3.png]



== Future plans ==

- use of the Cytoscape's [CytoTalk plugin CY_PLUGINS] to let PNC to
  communicate directly with Cytoscape (with this feature, PNC will be able to
  modify the network loaded in Cytoscape)
- create some documentation for the library



== Installation ==[install]

=== Requirements ===

Only Python is required to run pyNetConv. You can get it from the [Python web site http://python.org].


=== Install from source ===

Download the files from the [project page PRJ_PAGE].

After unpacking the file, execute:

```
python setup.py install
```

in the package new created folder to install it.

To use the graphical interface run the file ``netconv-gui.py``.

=== Win32 installation ===

For Windows, you can download the Win32 installer (with extension ``.exe``). If you want the documentation of the API, you should also download the source code (it is not included in the Win32 installer).


== ChangeLog ==[changelog]

Moved to a [separate file changelog.html]


== FAQ ==

: **What is the multiplier in the GML export function?**

  Pejek stores the nodes coordinates using a number between 0 and 1,
  representing the position on the graph as a percent value.

  GML files store this information as absolute values representing the
  position on the graph.

  To convert from GML to Pajek, PNC divides all the positions by the biggest
  value, generating values between 0 and 1, but for Pajek to GML, there is no
  easy way to guess the value to convert (it depends on many factors, as the
  number of nodes, their positions, etc), so the user should inform a value
  to multiply all the coordinates in Pajek to put them in the GML file. The
  user should find out the one that fits best to his/her network. A good
  start is 1000.
  
: **I am using Windows. Where is ``netconv-gui.py`` installed?**

  In the Python scripts folder. For example, for Python 2.4 it should be:

```
C:\Python24\Scripts\
```


%!include: footer.t2t