release: v0.1

.github/workflows/tests.yml

@@ -0,0 +1,58 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: Tests
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+
+jobs:
+  build:
+
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.9", "3.10"]
+        os: ["ubuntu-latest", "windows-latest"]
+        exclude:
+          - os: macos-latest
+            python-version: "3.8"
+          - os: macos-latest
+            python-version: "3.9"
+          - os: windows-latest
+            python-version: "3.8"
+          - os: windows-latest
+            python-version: "3.9"
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+        pip install -r requirements-tests.txt
+    - name: Lint with pylint
+      run: |
+        make lint
+    - name: Test with pytest
+      run: |
+        make test
+    - name: Generate coverage report
+      run: |
+        make codecov-xml
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v3
+      with:
+        flags: unittests
+        name: codecov-umbrella
+        fail_ci_if_error: true
+        verbose: true
+

.gitignore

@@ -56,6 +56,11 @@ coverage.xml
 .pytest_cache/
 .benchmarks
 
+# Codecov
+*.gcno
+*.gcda
+*.gcov
+
 # Translations
 *.mo
 *.pot

.readthedocs.yaml

@@ -0,0 +1,25 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+# formats:
+#    - pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - requirements: docs/requirements.txt 

Makefile

@@ -44,6 +44,9 @@ test:
 test-all:
 	tox
 
+test-all-p:
+	tox -p auto
+
 cov-run:
 	coverage run --source pathcensus setup.py test
 
@@ -54,6 +57,9 @@ cov-report:
 
 coverage: cov-run cov-report
 
+codecov-xml:
+	pytest --cov=./pathcensus --cov-report=xml
+
 docs:
 	rm -f docs/pathcensus.rst
 	rm -f docs/modules.rst

README.rst

@@ -2,11 +2,11 @@
 ``pathcensus`` package
 =============================
 
-.. image:: https://badge.fury.io/py/pathcensus.png
-    :target: http://badge.fury.io/py/pathcensus
+.. image:: https://github.com/sztal/pathcensus/actions/workflows/tests.yml/badge.svg
+ :target: https://github.com/sztal/pathcensus
 
-.. image:: https://travis-ci.org/sztal/pathcensus.png?branch=master
-    :target: https://travis-ci.org/sztal/pathcensus
+.. image:: https://codecov.io/gh/sztal/pathcensus/branch/master/graph/badge.svg?token=HP4hLAnagg
+ :target: https://codecov.io/gh/sztal/pathcensus
 
 
 Welcome to the documentation of ``pathcensus`` package.
@@ -37,7 +37,23 @@ automatically to sparse matrices. Conversion methods for `networkx`_,
 `igraph`_ and `graph-tool`_ are registered automatically
 provided the packages are installed.
 
-For the sake of convenience ``pathcensus`` provides also implementations
+**NOTE**
+
+    ``pathcensus`` uses the ``A_{ij} = 1`` convention to indicate
+    that a node `i` sends a tie to a node `j`. Functions converting
+    graph-like objects to arrays / sparse matrices need to be aware
+    of that.
+
+**NOTE**
+
+    ``pathcensus`` is compatible only with Python versions supported
+    by `numba`_. In practice it means that it is compatible with all
+    versions (starting from 3.8) except for the latest one, which usually
+    starts to be supported by `numba`_ with some (often significant)
+    delay.
+
+
+For the sake of convenience ``pathcensus`` also provides implementations
 of most appropriate null models for statistical calibration of structural
 coefficients which are simple wrappers around the excellent `NEMtropy`_
 package. It also defines the ``pathcensus.inference`` submodule with
@@ -46,15 +62,15 @@ sampling from null models.
 
 See ``examples`` subfolder and the main documentation for more details.
 
-At the command line via pip
+At the command line via pip:
 
 .. code-block::
 
-    # Not yet on PyPI
+    # Install from PyPI
     pip install pathcensus
 
-The current (unstable) development version can be installed
-directly from the `github repo`_
+The current development version (not guaranteed to be stable)
+can be installed directly from the `github repo`_
 
 .. code-block::
 
@@ -68,8 +84,8 @@ You find the package useful? Please cite our work properly.
 
 **Main theory paper**
 
-    Talaga, S., & Nowak, A. (2022). Structural complementarity and similarity:
-    linking relational principles to network structure. arXiv preprint arXiv:2201.03664.
+    Talaga, S., & Nowak, A. (2022). Structural measures of similarity and complementarity
+    in complex networks. *Scientific Reports*, (in press).
 
 
 Usage
@@ -84,7 +100,7 @@ Usage
 
 We will use `igraph`_ to generate graphs used in examples. However, even though
 it is automatically integrated with ``pathcensus``, `igraph`_ is not
-a dependency.
+a dependency and needs to be installed separately.
 
 .. code-block:: python
 
@@ -228,6 +244,11 @@ by using ``parallel=True``.
     time ``parallel=True`` is used there will be a significant extra
     overhead.
 
+**NOTE**
+
+    The ``parallel=True`` argument may not work and lead to segmentation
+    faults on some MacOS machines.
+
 .. code-block:: python
 
     # By default all available threads are used
@@ -261,7 +282,7 @@ from the `github repo`_.
 
 It is recommended to work within an isolated virtual environment.
 This can be done easily for instance using `conda`_.
-Remember about using a proper Python version (e.g. 3.8 or 3.9).
+Remember about using a proper Python version (i.e. 3.8+).
 
 .. code-block::
 

docs/conf.py

@@ -17,6 +17,7 @@
 # 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.
 sys.path.insert(0, os.path.abspath("."))
+sys.path.insert(0, os.path.abspath(".."))
 
 import pathcensus
 
@@ -83,7 +84,7 @@
 
 # General information about the project.
 project = "Path census"
-copyright = "2021, Szymon Talaga"
+copyright = "2022, Szymon Talaga"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

docs/requirements.txt

@@ -0,0 +1,2 @@
+-r ../requirements.txt
+-r ../requirements-docs.txt

docs/sections/citation.rst

@@ -3,7 +3,7 @@ How to cite?
 
 You find the package useful? Please cite our work properly.
 
-`Main theory paper <https://arxiv.org/abs/2201.03664>`_
+**Main theory paper**
 
-    Talaga, S., & Nowak, A. (2022). Structural complementarity and similarity:
-    linking relational principles to network structure. arXiv preprint arXiv:2201.03664.
+    Talaga, S., & Nowak, A. (2022). Structural measures of similarity and complementarity
+    in complex networks. *Scientific Reports*, (in press).

docs/sections/installation.rst

@@ -8,8 +8,8 @@ At the command line via pip
 
     pip install pathcensus
 
-The current (unstable) development version can be installed
-directly from the `github repo`_
+The current development version (not guaranteed to be stable)
+can be installed directly from the `github repo`_
 
 .. code-block::
 
@@ -28,7 +28,7 @@ from the `github repo`_.
 
 It is recommended to work within an isolated virtual environment.
 This can be done easily for instance using `conda`_.
-Remember about using a proper Python version (e.g. 3.8 or 3.9).
+Remember about using a proper Python version (i.e. 3.8+).
 
 .. code-block::
 

docs/sections/overview.rst

@@ -29,6 +29,14 @@ automatically to sparse matrices. Conversion methods for `networkx`_,
 `igraph`_ and `graph-tool`_ are registered automatically
 provided the packages are installed.
 
+.. note::
+
+    ``pathcensus`` is compatible only with Python versions supported
+    by `numba`_. In practice it means that it is compatible with all
+    versions (starting from 3.8) except for the latest one, which usually
+    starts to be supported by `numba`_ with some (often significant)
+    delay.
+
 For the sake of convenience ``pathcensus`` provides also implementations
 of most appropriate null models for statistical calibration of structural
 coefficients which are simple wrappers around the excellent `NEMtropy`_

pathcensus/graph.py

@@ -17,6 +17,13 @@
 and :py:mod:`graph_tool` are registered automatically provided
 the packages are installed.
 
+.. note::
+
+    ``pathcensus`` uses the ``A_{ij} = 1`` convention to indicate
+    that a node `i` sends a tie to a node `j`. Functions converting
+    graph-like objects to arrays / sparse matrices need to be aware
+    of that.
+
 Below is an example in which a custom conversion from a list of list
 format is registered. Arguably, the below implementation is naive and
 handles the conversion by simply converting to a :py:mod:`numpy` array,
@@ -137,7 +144,7 @@ def _adj_spmat(graph: spmatrix) -> spmatrix:
     import networkx as nx     # tyoe: ignore
     def _adj_nx(graph: nx.Graph, **kwds: Any) -> spmatrix:
         """Adjacency matrix from :py:class:`networkx.Graph` object."""
-        adj = nx.convert_matrix.to_scipy_sparse_matrix(graph, **kwds)
+        adj = nx.convert_matrix.to_scipy_sparse_array(graph, **kwds)
         return adjacency(adj)
     # Register as GraphABC subclass
     GraphABC.register_type(nx.Graph, _adj_nx)

pathcensus/inference.py

@@ -76,7 +76,6 @@
 from typing import Sequence, Tuple, Dict, Callable, Literal, Union
 from dataclasses import dataclass
 import numpy as np
-import numba
 import pandas as pd
 from statsmodels.stats.multitest import fdrcorrection_twostage
 from tqdm.auto import tqdm

pathcensus/nullmodels/ubcm.py

@@ -36,12 +36,10 @@
     >>> # from the observed sequence
     >>> (np.abs(ubcm.ED - ubcm.D) <= 1e-6).all()
     True
-    >>> # Set seed of null model sampler and sample ensemble instance
-    >>> from pathcensus.utils import set_seed
-    >>> set_seed(17)
-    >>> ubcm.sample_one()
+    >>> # Sample a single ensemble instance
+    >>> ubcm.sample_one()    # doctest: +ELLIPSIS
     <20x20 sparse matrix of type '<class 'numpy.uint8'>'
-    	with 84 stored elements in Compressed Sparse Row format>
+    	with ... stored elements in Compressed Sparse Row format>
     >>> # Sample multiple instances (generator)
     >>> for instance in ubcm.sample(10): pass
 """

pathcensus/nullmodels/uecm.py

@@ -46,12 +46,10 @@
     >>> # from the observed sequence
     >>> (np.abs(uecm.ES - uecm.S) <= 1e-6).all()
     True
-    >>> # Set seed of null model sampler and sample one instance
-    >>> from pathcensus.utils import set_seed
-    >>> set_seed(44)
-    >>> uecm.sample_one()
+    >>> # Sample a single instance
+    >>> uecm.sample_one()    # doctest: +ELLIPSIS
     <20x20 sparse matrix of type '<class 'numpy.int64'>'
-    	with 68 stored elements in Compressed Sparse Row format>
+    	with ... stored elements in Compressed Sparse Row format>
     >>> # Sample multiple instances (generator)
     >>> for instance in uecm.sample(10): pass
 """

pathcensus/pathcensus.py

@@ -424,6 +424,11 @@ def count_paths(
             Passed to :py:func:`pathcensus.core.parallel.count_paths_parallel`
             when ``parallel=True``.
 
+        Notes
+        -----
+        The ``parallel=True`` argument may not work and lead to segmentation
+        faults on some MacOS machines.
+
         Returns
         -------
         n_nodes