README.md

# viz-layout

## Description

The viz-layout is a layout to draw metabolic pathways vertically. To use the layout, a network with nodes and directed links is required. User can provide an object describing the network style, thus a style attributs can be associated with nodes. If defined in the network style, height and width of nodes will be taken into account. The layout change the position of nodes, and can add some classes for nodes and links.  

The layout has been thinked to be executed on a directed bipartite graph where metabolite nodes are only linked to reaction nodes. A reaction can be reversible, links for a reversible reaction all have to be delared in the same direction. To reverse the reaction, the source and target of the links are inversed. A metabolite node can be declare as a side compounds. Classic examples of nodes that can de declared as such are water and ATP.


## Getting started

#### Create a typescript project

1. **Initialize a new project**

   First, create a new directory for your project and initialize it with `npm`:

   ```bash
   mkdir my-project
   cd my-project
   npm init -y
   ```

2. **Install TypeScript**

    You'll need to install TypeScript as a development dependency in your project:

    ```bash
    npm install --save-dev typescript
    ```

3. **Set up the TypeScript configuration**

    TypeScript requires a `tsconfig.json` file (at the root of the project) to specify how your TypeScript code should be compiled. You can generate a default configuration file by running:

    ```bash
    npx tsc --init
    ```

   

4. **Create your source files**

    Inside your project, create a `src` directory for your TypeScript code:

    ```bash
    mkdir src
    ```


#### Install via npm

The viz-layout package is currently only available on the MetaboHUB forge. To install it, you need to configure an `.npmrc` file (at the root of the project) to specify the retrieval path.

```.npmrc
@metabohub:registry=https://forgemia.inra.fr/api/v4/packages/npm/
```

Then you can install the package:

```
npm install @metabohub/viz-layout
```

#### Typescript configuration


Once the installation step is completed, you need to declare the module. To do this, add the following line in the `env.d.ts` file (at the root of the project):

```ts 
declare module "@metabohub/viz-layout";
```


## Usage


```typescript
// Imports
import type { Network , Node, Link, GraphStyleProperties, NodeStyle} from "@metabohub/viz-layout/src/types/TypeVizCore";
import { algorithmOnNetwork } from "@metabohub/viz-layout"

// Creation of network
const nodes : {[key:string]:Node} = {
	A: {
		id: 'A',
		x: 50,
		y: 50,
        classes: ["metabolite"],
        metadata :{
            isSideCompound : false
        }
	},
	B: {
		id: 'B',
		x: 100,
		y: 100,
        classes: ["reaction"],
        metadata : {
            isReversible : true
        }
	}
}
const links : Link[] = [
	{
		source: nodes.A,
		target: nodes.B,
		id: 'A->B'
	}
]
const network:Network = { id: 'network', nodes: nodes, links: links };


// Creation of network styles
const nodeStyle : NodeStyle = {
            metabolite: {
                height: 50,
                width: 50
            },
            reaction: {
                height: 100,
                width: 100
            }
        };
const networkStyle :GraphStyleProperties ={ nodeStyles: nodeStyle };

// Choosing parameters
const parameters = defaultParameters;
parameters.doReactionReversible = false;

// Application of layout
const newNetwork = await algorithmOnNetwork(network, networkStyle, parameters);
```


## Types 

### Types for network

##### Network

| Attribut | Type | Description |
| -------- | ---- | ----------- |
| id | `string` | Network's id |
| nodes | `{[key: string] Node}` | Object that contains nodes |
| links | `Array<Link>` | List that contains links |


##### Node

| Attribut | Type | Description |
| -------- | ---- | ----------- |
| id | `string` | Node's id |
| x | `number` | X node's position |
| y | `number` | Y node's position |
| classes | `Array<string>` | Node's classes to manage style |
| metadata | `{[key: string]: string \| number \| {[key: string]: string \| number} \| Array<string> \| boolean}` | Node's metadata |


<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-exclamation-triangle-fill" viewBox="0 0 16 16">
  <path d="M8.982 1.566a1.13 1.13 0 0 0-1.96 0L.165 13.233c-.457.778.091 1.767.98 1.767h13.713c.889 0 1.438-.99.98-1.767zM8 5c.535 0 .954.462.9.995l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 5.995A.905.905 0 0 1 8 5m.002 6a1 1 0 1 1 0 2 1 1 0 0 1 0-2"/>
</svg> 
The id of the node has to be the same that the key associated with the node in 'nodes' in the network !

<br />
<br />

The classes of a node can contain at least either `metabolite` or `reaction`.

Metadata can contains those elements :
| Key | Type | Description |
| -------- | ---- | ----------- |
| isSideCompound | `booleen` | Node is declared as a side compound |
| isReversible | `booleen` | Node is declared as a reversible |

If `isSideCompound` is not set, the step to manage side compounds won't do anything. A class `duplicate` will be added to side compounds nodes that have been duplicated.
If `isReversible` is not set and reaction node doesn't contains a class "reaction", the step to manage reaction reversible won't do anything : there is no reaction that are reversible.


##### Link

| Attribut | Type | Description |
| -------- | ---- | ----------- |
| id | string | Link's id |
| source | Node | Source node of the link |
| target | Node | Target node of the link |
| classes | Array<string> | Link's classes to manage style |

<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-exclamation-triangle-fill" viewBox="0 0 16 16">
  <path d="M8.982 1.566a1.13 1.13 0 0 0-1.96 0L.165 13.233c-.457.778.091 1.767.98 1.767h13.713c.889 0 1.438-.99.98-1.767zM8 5c.535 0 .954.462.9.995l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 5.995A.905.905 0 0 1 8 5m.002 6a1 1 0 1 1 0 2 1 1 0 0 1 0-2"/>
</svg> The source and target need to be pointer to a node present in the network (see usage) ! 

In order to have a bipartite graph, links should associate a metabolite node with a reaction node.
A class `reversible` will be added by the layout for links associated with a reversible reaction if the step to manage reversible reaction is done. 

### Types for style

#### GraphStyleProperties

| Attribut | Type | Description |
| -------- | ---- | ----------- |
| nodeStyles | { [key: string]: NodeStyle } | Object that contains nodes classes name associated to their style |

The keys of nodeStyles need to be the same that classes of nodes to associate the style to nodes.

#### NodeStyle

| Attribut | Type | Description |
| -------- | ---- | ----------- |
| height | number | Node's height |
| width | number | Node's width |


### Types for parameters

...

## Function

### algorithmOnNetwork

Is a asynchronous function.

##### Input

| Arguments | Type | default | Description | Optional |
| ----- | ---- | ------- | ----------- | -------- |
| network | `Network` | - | Network object that contains nodes and links of the network | No |
| networkStyle | `GraphStyleProperties` | {} | Network style object that contains classes and style associated with nodes | Yes |
| parameters | `Parameters` | defaultParameters | Parameters of the step of layout | Yes |

To change parameters, you need to get defaultParameters and then modify the accessible attributs.

##### Output

 Type | Description 
 ---- | ----------- 
 `Network` | network with modified node positions, and some added classes  


#### Step of the layout

##### Base Layout

...
  
##### Management of side compounds

Nodes declared as side compounds are duplicated if `doDuplicateSideCompounds` is true.
Nodes declared as side compounds are removed from the network object if `doPutAsideSideCompounds` is true. They can be temporary suppressed so that they are placed depending on the positions of the other nodes.

At the end of the algrithm, side compounds are reinserted in the network if `doPutAsideSideCompounds` is true (if they have been removed in the first place), and if `doDuplicateSideCompounds` is true. If side compounds are suppressed whitout having been duplicated, there is no method implemented to reinsert them.

| `doDuplicateSideCompounds` | `doPutAsideSideCompounds` | Reinsertion of side compounds ? |
|---|---|---|
| true | true | true |
| false | false | false |
| true | false | false |
| false | true | false |




##### Management of reversible reaction

For the step to have an effect


##### Management of directed cycles
% dont choix reaction rev
Les circuits de plus de trois nœuds du graphe sont détectés et conservés dans une liste. L'algorithme de détection a été adapté pour que les circuits trouvés ne contiennent pas à la fois le nœud d'origine et sa version réversible. Les circuits sont triés par taille décroissante et pour chacun les versions réversibles des nœuds des circuits sont supprimées. Les circuits n'existant plus dû aux suppressions sont retirés de la liste. 




##### Management of main chains
Les chaînes principales sont détectées et les produits sans nœuds fils liés aux réactions de la chaîne y sont ajoutés (cf. \ref{chaîne}).
+ mini branch



#### Shifting coordinates