diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000000000000000000000000000000000000..69fe55ecfa9aade66e1412aef0ee7d04a9bcde86 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 0000000000000000000000000000000000000000..543c6b13b473ff3c586d5d97ae418d267ee795c4 --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/doc/source/api.rst b/doc/source/api.rst new file mode 100644 index 0000000000000000000000000000000000000000..63810326544cbcee557c2b9ff7d57045b3c7e736 --- /dev/null +++ b/doc/source/api.rst @@ -0,0 +1,22 @@ +.. _api: + +================ +Alignment module +================ + +.. automodule:: wlalign.alignment + :members: permutation_from_alignment, apply_alignment, length_wl_signature, signature_wl, wl_align + +================= +Similarity module +================= + +.. automodule:: wlalign.similarity + :members: graph_jaccard_index + +============ +Utils module +============ + +.. automodule:: wlalign.utils + :members: load_network, symmetrize_adj, check_is_adj, check_compatible_adj, check_is_alignment, check_can_write_file diff --git a/doc/source/citation.rst b/doc/source/citation.rst new file mode 100644 index 0000000000000000000000000000000000000000..a94636cc1f2a12d6bb7cf2a90b0799fc2bf2071f --- /dev/null +++ b/doc/source/citation.rst @@ -0,0 +1,27 @@ +.. _citation: + +==================== +How to cite WL-align +==================== +If you use WL-align in your research, please cite the following article. + + Matteo Frigo, Emilio Cruciani, David Coudert, Rachid Deriche, Emanuele + Natale, Samuel Deslauriers-Gauthier; Network alignment and similarity + reveal atlas-based topological differences in structural connectomes. + Network Neuroscience 2021; + `DOI: 10.1162/netn_a_00199 <https://doi.org/10.1162/netn_a_00199>`_ + +.. code:: bibtex + + @article{wlalign, + author = {Frigo, Matteo and Cruciani, Emilio and Coudert, David and + Deriche, Rachid and Natale, Emanuele and + Deslauriers-Gauthier, Samuel}, + title = {Network alignment and similarity + reveal atlas-based topological differences in structural + connectomes}, + journal = {Network Neuroscience}, + url = {https://hal.archives-ouvertes.fr/hal-03116143}, + doi = {10.1162/netn_a_00199}, + year = {2021} + } diff --git a/doc/source/command-line-interface.rst b/doc/source/command-line-interface.rst new file mode 100644 index 0000000000000000000000000000000000000000..8512ef3f4bffc6ef8dbad74106318ce08c49aaf2 --- /dev/null +++ b/doc/source/command-line-interface.rst @@ -0,0 +1,41 @@ +.. _command-line-interface: + +=========================== +CLI: Command Line Interface +=========================== + +The user can align two graphs from the command line by providing their +adjacency matrices in text form. +The edge weights in each line must be separated by whitespaces. + +.. code:: bash + + wlalign --help + +.. code:: text + + usage: wlalign [-h] [--first_aligned FIRST_ALIGNED] [--k INT] [--l INT] + [--force] [-v] + in_graph1 in_graph2 out_matching + + This program uses WL-align to compute an alignment between two graphs having + the same number of nodes. It takes as input their adjacency matrices and it + returns a matching (a.k.a. alignment) between their nodes. + + positional arguments: + in_graph1 Path to the first graph to be aligned + in_graph2 Path to the second graph to be aligned + out_matching Path where the matching will be saved. The first + element of each row is the index of the node in the + first graph that is aligned with the node in the + second graph indexed by the second element of the row + + optional arguments: + -h, --help show this help message and exit + --first_aligned FIRST_ALIGNED + The aligned version of the first input graph will be + saved in the specified position (default: None) + --k INT Width parameter (default: 2) + --l INT Depth parameter (default: 2) + --force Overwrite existing files (default: False) + -v, --verbose Set verbose output (default: False) diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000000000000000000000000000000000000..ec0f949a82831a5340be44fd5fab34366af6d76c --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,198 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +import wlalign +sys.path.insert(0, os.path.abspath(os.path.join('..', '..'))) + + +# -- Project information ----------------------------------------------------- + +project = 'WL-align' +copyright = '2021, CoBCoM' +author = 'Matteo Frigo, Emilio Cruciani, David Coudert, Rachid Deriche, ' \ + 'Emanuele Natale, Samuel Deslauriers-Gauthier' + +# The short X.Y version +version = wlalign.__version__ +# The full version, including alpha/beta/rc tags +release = wlalign.__version__ + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.mathjax', + 'sphinx.ext.napoleon', + 'sphinx.ext.viewcode', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +html_theme_options = { + 'nosidebar': True, +} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +# html_static_path = ['_static'] +html_static_path = [] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'wlaligndoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'wlalign.tex', 'WL-align Documentation', + 'Matteo Frigo, Emilio Cruciani, David Coudert, Rachid Deriche, ' \ + 'Emanuele Natale, Samuel Deslauriers-Gauthier', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'wlalign', 'wlalign Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'wlalign', 'WL-align Documentation', + author, 'wlalign', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + + +# -- Extension configuration ------------------------------------------------- +# Napoleon +napoleon_google_docstring = True +napoleon_numpy_docstring = True +napoleon_include_init_with_doc = True +napoleon_include_private_with_doc = False +napoleon_include_special_with_doc = False +napoleon_use_admonition_for_examples = False +napoleon_use_admonition_for_notes = False +napoleon_use_admonition_for_references = False +napoleon_use_ivar = False +napoleon_use_param = True +napoleon_use_rtype = True diff --git a/doc/source/contributors.rst b/doc/source/contributors.rst new file mode 100644 index 0000000000000000000000000000000000000000..63ce733acddd7f0db8addaf4fd14cb1c41766177 --- /dev/null +++ b/doc/source/contributors.rst @@ -0,0 +1,12 @@ +.. _contributors: + +==================== +List of Contributors +==================== +WL-align was conceived in the COATI and ATHENA Project Teams at Inria Sophia +Antipolis - Méditerranée. The Python package was developed by: + +* `Matteo Frigo <https://www.mfrigo.com>`_ , ATHENA Project Team, Inria Sophia + Antipolis - Méditerranée. +* `Emilio Cruciani <https://sites.google.com/view/emiliocruciani/>`_ , COATI + Project Team, Inria Sophia Antipolis - Méditerranée. diff --git a/doc/source/funding.rst b/doc/source/funding.rst new file mode 100644 index 0000000000000000000000000000000000000000..b97fa77e64d40b6a92e89c6775b9a92f33a9c5b3 --- /dev/null +++ b/doc/source/funding.rst @@ -0,0 +1,13 @@ +.. _funding: + +==================== +Funding +==================== +The development of WL-align was funded by the European Research Council (ERC) +under the European Union’s Horizon 2020 research and innovation program (ERC +Advanced Grant agreement No 694665: `CoBCoM - Computational Brain Connectivity +Mapping <https://project.inria.fr/cobcom/>`_ ). + +.. image:: img/logo_erc_eu.jpg + :align: center + :width: 600 diff --git a/doc/source/img/logo_erc_eu.jpg b/doc/source/img/logo_erc_eu.jpg new file mode 100644 index 0000000000000000000000000000000000000000..16c972ea3ac24562f4b0dff8245a74259aba6a4b Binary files /dev/null and b/doc/source/img/logo_erc_eu.jpg differ diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..e3b0b9987ecdd5b0f3964a0c058f82fbb3ac5c41 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,92 @@ +==================================== +Welcome to WL-align's documentation! +==================================== + +.. image:: https://gitlab.inria.fr/cobcom/wlalign/badges/master/pipeline.svg + :target: https://gitlab.inria.fr/cobcom/wlalign/-/commits/master" + :alt: Pipeline Status + +.. image:: https://gitlab.inria.fr/cobcom/wlalign/badges/master/coverage.svg + :target: https://gitlab.inria.fr/cobcom/wlalign/-/commits/master + :alt: Coverage Report + + +`wlalign` is a pure Python package that implements the graph-alignment routine +based on the generalization of the Weisfeiler-Lehman algorithm proposed in +`this paper <https://doi.org/10.1162/netn_a_00199>`_. + +The software provides the ``wlalign`` Python module, which includes all the +**functions and tools that are necessary for computing network alignments and +similarity**. +In particular, specific functions are devoted to: + +* Computing the **graph Jaccard index** of **similarity** between two weighted graphs. +* Solving the **graph alignment problem** with **WL-align**. + +The package is `available at Pypi <#>`_ and can be easily installed from the +command line. + +.. code:: bash + + pip install wlalign + + +Talon is a free software released under `MIT license <LICENSE>`_. + +Getting help +============ +The preferred way to get assistance in running code that uses WL-align is +through the issue system of the +`Gitlab repository <https://gitlab.inria.fr/cobcom/wlalign>`_ where the +source code is available. +Developers and maintainers frequently check newly opened issues and will be +happy to help you. + + +Contributing guidelines +======================= +The development happens in the ``devel`` branch of the +`Gitlab repository <https://gitlab.inria.fr/cobcom/wlalign>`_, while the +``master`` is kept for the stable releases only. +We will consider only merge requests towards the ``devel`` branch. + + +How to cite +=========== +If you publish works using WL-align, please cite us as indicated here: + + Matteo Frigo, Emilio Cruciani, David Coudert, Rachid Deriche, Emanuele + Natale, Samuel Deslauriers-Gauthier; Network alignment and similarity + reveal atlas-based topological differences in structural connectomes. + Network Neuroscience 2021; doi: https://doi.org/10.1162/netn_a_00199 + +In section :ref:`citation` you will find the Bibtex entry. + + +.. toctree:: + :maxdepth: 2 + :caption: Install + + installation + +.. toctree:: + :maxdepth: 2 + :caption: Command Line Interface + + command-line-interface + + +.. toctree:: + :maxdepth: 2 + :caption: API documentation + + api + +.. toctree:: + :maxdepth: 1 + :caption: About the project + + citation + contributors + license + funding diff --git a/doc/source/installation.rst b/doc/source/installation.rst new file mode 100644 index 0000000000000000000000000000000000000000..6e098d1396ef13f885d174b6ecf85272a54285a1 --- /dev/null +++ b/doc/source/installation.rst @@ -0,0 +1,104 @@ +.. _installation: + +============ +Installation +============ +WL-align runs only on Python 3. +The installation has the following dependencies: + +* Numpy +* Scipy + +If you are an Anaconda user, you may want to create a dedicated ``wlalign-env`` +environment and populate it with the right dependencies, then install WL-align. + +.. code:: bash + + conda env create -n wlalign-env -f environment.yml + pip install wlalign + +Alternatively, you can install the dependencies and WL-align all via ``pip``. + +.. code:: bash + + pip install numpy + pip install scipy + + pip install wlalign + +To install WL-align directly from the source, clone this repository and run the +standard local setup commands. + +.. code:: bash + + git clone https://gitlab.inria.fr/cobcom/wlalign.git + cd wlalign + pip install -U . + + +Check installation +================== +To check that WL-align has been properly installed, try to import the ``wlalign`` +module into a Python session and print the version as follows. If no error is +raised, the installation has been successful. + +.. code:: python + + >>> import wlalign + >>> print(wlalign.__version__) + + +For developers +============== +If you are thinking about developing your own fork of WL-align, you may want to +use the latest version in the ``devel`` branch of the repository and install it +in editable mode. + +.. code:: bash + + git clone https://gitlab.inria.fr/cobcom/wlalign.git + cd WL-align + git checkout devel + pip install -e . + + +Tests +~~~~~ +The package uses ``unittest`` as a testing suite. +To run all the tests, execute the following command in the source's root +directory. + +.. code:: bash + + python -m unittest -v + +Test coverage can be checked with ``coverage`` as follows. + +.. code:: bash + + coverage run -m unittest + coverage report -m + + +Documentation +~~~~~~~~~~~~~ +The sources of the documentation are in the ``doc`` folder. +The compilation requires the ``sphinx`` package and the theme to be installed. + +.. code:: bash + + pip install sphinx + pip install sphinx_rtd_theme + +To compile the documentation, move to the ``doc`` folder and run +``make <format>``, where the format can be ``html``, ``latex`` or any other +sphinx-compatible format. +To get a local copy of the the html documentation, run the ``make html`` +command. + +.. code:: bash + + cd doc + make clean # deletes results of previous compilations + make html + diff --git a/doc/source/license.rst b/doc/source/license.rst new file mode 100644 index 0000000000000000000000000000000000000000..8528545eba6e90436c3753596678ee25a00dd81d --- /dev/null +++ b/doc/source/license.rst @@ -0,0 +1,26 @@ +.. _license: + +==================== +License +==================== +MIT License + +Copyright (c) 2021 WL-align developers + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE.