# Quick Start¶

`CDlib`

is a python library that allows to extract, compare and evaluate network partitions.
We designed it to be agnostic w.r.t. the data structure used to represent the network to be clustered: all the algorithms it implements accept interchangeably igraph/networkx objects.

Of course, such a choice comes with advantages as well as drawbacks. Here’s the main ones you have to be aware of:

**Advantages**
- Easy integration of existing/novel (python implementation of) CD algorithms;
- Standardization of input and output;
- Zero-configuration user interface (e.g., you don’t have to reshape your data!)

**Drawbacks**
- Algorithms performances are not comparable (execution time, scalability… they all depends on how each algorithm was originally implemented);
- Memory (in)efficiency: depending by the type of structure each individual algorithm requires memory consumption could be high;
- Hidden transformation times: usually not a bottleneck, moving from a graph representation to another can take “some” time (usually linear in the graph size)

Most importantly: remember that i) each algorithm will be able to handle graphs up to a given size, and that ii) that maximum size that may vary greatly across the exposed algorithms.

## Tutorial¶

Extracting communities using `CDlib`

is easy as this:

```
from cdlib import algorithms
import networkx as nx
G = nx.karate_club_graph()
coms = algorithms.louvain(G, weight='weight', resolution=1., randomize=False)
```

Of course, you can choose among all the algorithms available (taking care of specifying the correct parameters): in any case, you’ll get as a result a Clustering object (or a more specific subclass).

Clustering objects expose a set of methods to perform evaluation and comparisons. For instance, to get the partition modularity just write

```
mod = coms.newman_girvan_modularity(g)
```

or, equivalently

```
from cdlib import evaluation
mod = evaluation.newman_girvan_modularity(g,communities)
```

Moreover, you can also visualize networks and communities, plot indicators and similarity matrices… just take a look to the module reference to get a few examples.

I know, plain tutorials are overrated: if you want to explore `CDlib`

functionalities, please start playing around with our interactive Google Colab Notebook!

## FAQ¶

**Q1.** I developed a novel Community Discovery algorithm/evaluation/visual analytics method and I would like to see it integrated in `CDlib`

. What should I do?

**A1.** That’s great! Just open an issue on the project GitHub briefly describing the method (provide a link to the paper where it has been firstly introduced) and links to a python implementation (if available). We’ll came back to you as soon as possible to discuss the next steps.

**Q2.** Can you add method XXX to your library?

**A2.** It depends. Do you have a link to a python implementation/are you willing to help us in implementing it? If so, that’s perfect. If not, well… everything is possible but it is likely that it will require some time.

**Q3.** I have a clustering obtained by an algorithm not included in `CDlib`

. Can I load it in a Clustering object to leverage the evaluation and visualization facilities of your library?

**A3.** Yes you can. Just transform your clustering in a list of lists (e.g., we represent each community as a list of node ids) and then create a NodeClustering object from it.

```
from cdlib import NodeClustering
communities = [[1,2,3], [4,5,6], [7,8,9,10,11]]
coms = NodeClustering(communities, graph=None, method_name="your_method")
```

Of course, to compute some evaluation scores/plot community-networks you’ll also have to pass the original graph (as igraph/networkx object) while building the NodeClustering instance.