Skip to content

Commit

Permalink
📝 docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@GiulioRossetti
GiulioRossetti committed Jun 8, 2023
1 parent 7d0b3f1 commit b24e402
Show file tree
Hide file tree
Showing 3 changed files with 85 additions and 101 deletions.
38 changes: 22 additions & 16 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# CDlib - Community Discovery Library
# CDlib - Community Detection Library
[![codecov](https://codecov.io/gh/GiulioRossetti/cdlib/branch/master/graph/badge.svg?token=3YJOEVK02B)](https://codecov.io/gh/GiulioRossetti/cdlib)
[![Build](https://github.com/GiulioRossetti/cdlib/actions/workflows/python-package.yml/badge.svg)](https://github.com/GiulioRossetti/cdlib/actions/workflows/python-package.yml)
[![Documentation Status](https://readthedocs.org/projects/cdlib/badge/?version=latest)](http://cdlib.readthedocs.io/en/latest/?badge=latest)
Expand All @@ -15,11 +15,9 @@

[![Twitter](https://img.shields.io/twitter/url/https/twitter.com/_CDlib_.svg?style=social&label=Follow%20%40_CDlib_)](https://twitter.com/_CDlib_)

<!---
[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2FGiulioRossetti%2Fcdlib.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2FGiulioRossetti%2Fcdlib?ref=badge_shield)
--->

``CDlib`` is a meta-library for community discovery in complex networks: it implements algorithms, clustering fitness functions as well as visualization facilities.

``CDlib`` is a meta-library for community detection in complex networks: it implements algorithms, clustering fitness functions as well as visualization facilities.


``CDlib`` is designed around the ``networkx`` python library: however, when needed, it takes care to automatically convert (from and to) ``igraph`` object so to provide an abstraction on specific algorithm implementations to the final user.
Expand Down Expand Up @@ -59,32 +57,40 @@ pip install cdlib

or conda
```bash
conda create -n cdlib python=3.9
conda config --add channels giuliorossetti
conda config --add channels conda-forge
conda install cdlib
```

### Optional Dependencies (pip package)
``CDlib`` relies on a few packages calling C code that can be cumbersome to install on Windows machines: to address such issue, the default installation does not try to install set up such requirements.
To simplify the installation process, the default installation does not include optional dependencies (e.g., ``graph-tool``). If you need them, you can install them manually or run the following command:

Such a choice has been made to allow (even) non *unix user to install the library and get access to its core functionalities.
```bash
pip install cdlib[C]
```

To integrate the standard installation with you can either:
This option, safe for *nix users, will install all those optional dependencies that require C code compilation.

- (Windows) manually install the optional packages (versions details are specified in ``requirements_optional.txt``) following the original projects guidelines, or
- (Linux/OSX) run the command:
```bash
pip install cdlib[pypi]
```

This option will install all those optional dependencies that are not available on conda/conda-forge.

```bash
pip install cdlib[C]
pip install cdlib[all]
```

Such caveat will install everything that can be easily automated under Linux/OSX.
This option will install all optional dependencies accessible with the flag ``C`` and ``pypi``.

#### (Advanced)

##### Graph-tool
The only optional dependency that will remain unsatisfied following the previous procedures will be ``graph-tool`` (used to add SBM models).
If you need it up and running, refer to the official [documentation](https://git.skewed.de/count0/graph-tool/wikis/installation-instructions) and install the conda-forge version of the package.
Due to some strict requirements, the installation of a subset of optional dependencies is left outside the previous procedures.

##### graph-tool
``CDlib`` integrates the support for SBM models offered by ``graph-tool``.
To install it refer to the official [documentation](https://git.skewed.de/count0/graph-tool/wikis/installation-instructions) and install the conda-forge version of the package (or the deb version if in a *nix system).

##### ASLPAw

Expand All @@ -100,7 +106,7 @@ In case this does not solve the issue, please refer to the official ``gmpy2`` [i

### Optional Dependencies (Conda package)

``CDlib`` relies on a few packages not available through conda: to install it please use pip:
``CDlib`` relies on a few packages not available through conda: to install them please use pip.

```bash
pip install pycombo
Expand Down
9 changes: 7 additions & 2 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,21 @@
.. |date| date::

CDlib - Community Discovery Library
CDlib - Community Detection Library
===================================

``CDlib`` is a Python software package that allows to extract, compare and evaluate communities from complex networks.

The library provides a standardized input/output for several existing Community Discovery algorithms.
The library provides a standardized input/output for several existing Community Detection algorithms.
The implementations of all CD algorithms are inherited from existing projects, each one of them acknowledged in the dedicated method reference page.

If you would like to test ``CDlib`` functionalities without installing it on your machine consider using the preconfigured Jupyter Hub instances offered by the H2020 `SoBigData++`_ research project.

If you use ``CDlib`` in your research please cite the following paper:

G. Rossetti, L. Milli, R. Cazabet.
**CDlib: a Python Library to Extract, Compare and Evaluate Communities from Complex Networks.**
Applied Network Science Journal. 2019. DOI:10.1007/s41109-019-0165-9

================ =================== ================== ========== ===============
**Date** **Python Versions** **Main Author** **GitHub** **pypl**
Expand Down
139 changes: 56 additions & 83 deletions docs/installing.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,138 +2,111 @@
Installing CDlib
****************

Before installing ``CDlib``, you need to have setuptools installed.
``CDlib`` *requires* python>=3.8.

=============
Quick install
=============

Get ``CDlib`` from the Python Package Index at pypl_.

or install it with
To install the latest version of our library just download (or clone) the current project, open a terminal and run the following commands:

.. code-block:: python
pip install cdlib
pip install -r requirements.txt
pip install -r requirements_optional.txt # (Optional) this might not work in Windows systems due to C-based dependencies.
pip install .
and an attempt will be made to find and install an appropriate version that matches your operating system and Python version.
Please note that ``CDlib`` requires Python>=3.8
You can install the development version with
Alternatively use pip

.. code-block:: python
pip install git+https://github.com/GiulioRossetti/cdlib.git
pip install cdlib
or conda

=====================
Optional Dependencies
=====================
.. code-block:: python
``CDlib`` relies on a few packages calling C code that can be cumbersome to install on Windows machines: to address such issue, the default installation does not try to install set up such requirements.
conda create -n cdlib python=3.9
conda config --add channels giuliorossetti
conda config --add channels conda-forge
conda install cdlib
Such a choice has been made to allow (even) Windows user to install the library and get access to its core functionalities.
To made available (most of) the optional packages you can either:
- (Windows) manually install the optional packages (versions details are specified in ``requirements_optional.txt``) following the original projects guidelines, or
- (Linux/OSX) run the command:
.. code-block:: python
You can install the development version directly from the GitHub repository with

pip install cdlib[C]
.. code-block:: python
pip install git+https://github.com/GiulioRossetti/cdlib.git
Such caveat will install everything that can be easily automated under Linux/OSX.
=====================
Optional Dependencies
=====================

--------
Advanced
--------
**Graph-tool**
^^^^^^^^^^^^
PyPi package
^^^^^^^^^^^^

The only optional dependency that will remain unsatisfied following the previous procedures will be **graph-tool** (used to add SBM models).
If you need it up and running, refer to the official `documentation <https://git.skewed.de/count0/graph-tool/wikis/installation-instructions>`_ and install the conda-forge version of the package.
To simplify the installation process, the default installation does not include optional dependencies (e.g., ``graph-tool``). If you need them, you can install them manually or run the following command:

**ASLPAw**
.. code-block:: python
Since its 2.1.0 release ``ASLPAw`` relies on ``gmpy2`` whose installation through pip is not easy to automatize due to some C dependencies.
To address such issue test the following recipe:
pip install cdlib[C]
.. code-block:: bash
This option, safe for GNU/Linux users, will install all those optional dependencies that require C code compilation.

conda install gmpy2
pip install shuffle_graph>=2.1.0 similarity-index-of-label-graph>=2.0.1 ASLPAw>=2.1.0
.. code-block:: python
pip install cdlib[pypi]
In case this does not solve the issue, please refer to the official ``gmpy2`` `installation <https://gmpy2.readthedocs.io/en/latest/intro.html#installation>`_ instructions.
This option will install all those optional dependencies that are not available on conda/conda-forge.

.. code-block:: python
======================
Installing from source
======================
pip install cdlib[all]
You can install from source by downloading a source archive file (tar.gz or zip) or by checking out the source files from the GitHub source code repository.
This option will install all optional dependencies accessible with the flag C and pypi.

``CDlib`` is a pure Python package; you don’t need a compiler to build or install it.
^^^^^^^^
Advanced
^^^^^^^^

-------------------
Source archive file
-------------------
Download the source (tar.gz or zip file) from pypl_ or get the latest development version from GitHub_
Due to some strict requirements, the installation of a subset of optional dependencies is left outside the previous procedures.

Unpack and change directory to the source directory (it should have the files README.txt and setup.py).
----------
graph-tool
----------

Run python setup.py install to build and install
``CDlib`` integrates the support for SBM models offered by ``graph-tool``.
To install it refer to the official `documentation <https://git.skewed.de/count0/graph-tool/wikis/installation-instructions>`_ and install the conda-forge version of the package (or the deb version if in a *nix system).
------
GitHub
ASLPAw
------
Clone the ``CDlib`` repostitory (see GitHub_ for options)

.. code-block:: python
git clone https://github.com/GiulioRossetti/cdlib.git

Change directory to CDlib

Run python setup.py install to build and install

If you don’t have permission to install software on your system, you can install into another directory using the --user, --prefix, or --home flags to setup.py.

For example
Since its 2.1.0 release ``ASLPAw`` relies on ``gmpy2`` whose installation through pip is not easy to automatize due to some C dependencies.
To address such issue test the following recipe:

.. code-block:: python
python setup.py install --prefix=/home/username/python
or
conda install gmpy2
pip install shuffle_graph>=2.1.0 similarity-index-of-label-graph>=2.0.1 ASLPAw>=2.1.0
.. code-block:: python
In case ASLPAw installation fails, please refer to the official ``gmpy2`` `repository <https://gmpy2.readthedocs.io/en/latest/intro.html#installation>`_.

python setup.py install --home=~
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Optional Dependencies (Conda package)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

or
``CDlib`` relies on a few packages not available through conda: to install them please use pip.

.. code-block:: python
python setup.py install --user
If you didn’t install in the standard Python site-packages directory you will need to set your PYTHONPATH variable to the alternate location. See http://docs.python.org/2/install/index.html#search-path for further details.

============
Requirements
============
------
Python
------

To use ``CDlib`` you need Python 3.6 or later.
pip install pycombo
pip install GraphRicciCurvature
conda install gmpy2
pip install shuffle_graph>=2.1.0 similarity-index-of-label-graph>=2.0.1 ASLPAw>=2.1.0
The easiest way to get Python and most optional packages is to install the Enthought Python distribution “Canopy” or using Anaconda.
In case ASLPAw installation fails, please refer to the official ``gmpy2`` repository `repository <https://gmpy2.readthedocs.io/en/latest/intro.html#installation>`_.

There are several other distributions that contain the key packages you need for scientific computing.


.. _pypl: https://pypi.python.org/pypi/CDlib/
.. _GitHub: https://github.com/GiulioRossetti/CDlib/

0 comments on commit b24e402

Please sign in to comment.