diff --git a/README.md b/README.md index 1380522b..572e678b 100644 --- a/README.md +++ b/README.md @@ -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) @@ -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_) - -``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. @@ -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 @@ -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 diff --git a/docs/index.rst b/docs/index.rst index a3f53c42..55a09c0f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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** diff --git a/docs/installing.rst b/docs/installing.rst index 879d868d..76d8c8c4 100644 --- a/docs/installing.rst +++ b/docs/installing.rst @@ -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 `_ 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 `_ 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 `_ 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 `_. - 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 `_. -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/