readme.hbs

# csv2gexf

> Converts graph data in CSV documents to a GEXF document.

The current version (0.0.2) does not support dynamic nor hierarchical graphs.


## Getting started

First install [NodeJS](https://nodejs.org) (version 5.6.0 or higher).

Then install the dependencies for this package:

```shell
$ npm install
```


## CSV Documents

The graph data is loaded from two CSV documents. The first should contain the nodes data, the second the edges data. The data must respect the following requirements.

Both CSV files should contain headers.


### Nodes CSV file
- One column should contain unique node ids.
- One column may contain the node labels.
- All other columns are either node attributes or visualizaton settings.
    - Attributes may be arbitrary values of type string, int, float or boolean.
    - Visualization settings must be either:
        - A color expressed as RGB components in the form `rgb(<r>,<g>,<b>)`, where `<r>`, `<g>` and `<b>` are integer values in the range [0–255].
        - A size expressed as a decimal scale. The default is 1.0.
        - A shape, which must be either `disc`, `square`, `triangle`, or `diamond`.

#### Edges CSV file
- One column should contain the source node ids.
- One column should contain the target node ids.
- One column may contain unique edge ids.
- One column may contain the edge labels.
- One column may contain the edge types, which must be either `directed`, `undirected` or `mutual`.
- One column may contain the edge weights, which must be (decimal) numbers.
- All other columns are either edge attributes or visualizaton settings.
    - Attributes may be arbitrary values of type string, int, float or boolean.
    - Visualization settings must be either:
        - A color expressed as RGB components in the form `rgb(<r>,<g>,<b>)`, where `<r>`, `<g>` and `<b>` are integer values in the range [0–255].
        - A thickness expressed as a (decimal) number. The default is 1.0.
        - A shape, which must be either `solid`, `dotted`, `dashed`, or `double`.


## Configuration and schemas

To convert the CSV data to a GEXF document you will need to call the `csv2gexf.convert` function in this package.
This function takes a configuration object as sole argument. This object contains settings such as where to save the resulting GEXF file. It also contains schema that specify the nature of the columns in the CSV tables. These schema are arrays which contain one item for each column in the order of the columns. Each item is either a string or an object. The strings are used to mark the columns that contain primary node or edges properties such as id, label, source, target, type and weight. Some of these are required, others are optional. The objects are used for columns that contain arbitrary attributes or visualization settings. The format of the configuration object is [documented in the API Reference](#csv2gexfconfig--object).


## Example

See `./example/start.js` for an example of how to use the convertor. This example loads the CSV files in `./example/csv/` and writes the resulting Gexf document as `result.gexf` in the `./example` directory.

Run this examples:

```shell
$ npm run example
```

## Dependencies

- [csv for NodeJS](https://www.npmjs.com/package/csv)
- [Gexf library for JavaScript](https://www.npmjs.com/package/gexf)
- [jsdoc-to-markdown](https://www.npmjs.com/package/jsdoc-to-markdown)


## API Reference
{{#module name="csv2gexf"~}}
{{>body~}}
{{>members~}}
{{/module}}

* * *

&copy; 2016, Wouter Van den Broeck