%% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[letterpaper,10pt,english]{sphinxmanual}
\ifdefined\pdfpxdimen
   \let\sphinxpxdimen\pdfpxdimen\else\newdimen\sphinxpxdimen
\fi \sphinxpxdimen=.75bp\relax
\ifdefined\pdfimageresolution
    \pdfimageresolution= \numexpr \dimexpr1in\relax/\sphinxpxdimen\relax
\fi
%% let collapsible pdf bookmarks panel have high depth per default
\PassOptionsToPackage{bookmarksdepth=5}{hyperref}

\PassOptionsToPackage{warn}{textcomp}
\usepackage[utf8]{inputenc}
\ifdefined\DeclareUnicodeCharacter
% support both utf8 and utf8x syntaxes
  \ifdefined\DeclareUnicodeCharacterAsOptional
    \def\sphinxDUC#1{\DeclareUnicodeCharacter{"#1}}
  \else
    \let\sphinxDUC\DeclareUnicodeCharacter
  \fi
  \sphinxDUC{00A0}{\nobreakspace}
  \sphinxDUC{2500}{\sphinxunichar{2500}}
  \sphinxDUC{2502}{\sphinxunichar{2502}}
  \sphinxDUC{2514}{\sphinxunichar{2514}}
  \sphinxDUC{251C}{\sphinxunichar{251C}}
  \sphinxDUC{2572}{\textbackslash}
\fi
\usepackage{cmap}
\usepackage[T1]{fontenc}
\usepackage{amsmath,amssymb,amstext}
\usepackage{babel}



\usepackage{tgtermes}
\usepackage{tgheros}
\renewcommand{\ttdefault}{txtt}



\usepackage[Bjarne]{fncychap}
\usepackage{sphinx}

\fvset{fontsize=auto}
\usepackage{geometry}


% Include hyperref last.
\usepackage{hyperref}
% Fix anchor placement for figures with captions.
\usepackage{hypcap}% it must be loaded after hyperref.
% Set up styles of URL: it should be placed after hyperref.
\urlstyle{same}


\usepackage{sphinxmessages}
\setcounter{tocdepth}{1}


% Jupyter Notebook code cell colors
\definecolor{nbsphinxin}{HTML}{307FC1}
\definecolor{nbsphinxout}{HTML}{BF5B3D}
\definecolor{nbsphinx-code-bg}{HTML}{F5F5F5}
\definecolor{nbsphinx-code-border}{HTML}{E0E0E0}
\definecolor{nbsphinx-stderr}{HTML}{FFDDDD}
% ANSI colors for output streams and traceback highlighting
\definecolor{ansi-black}{HTML}{3E424D}
\definecolor{ansi-black-intense}{HTML}{282C36}
\definecolor{ansi-red}{HTML}{E75C58}
\definecolor{ansi-red-intense}{HTML}{B22B31}
\definecolor{ansi-green}{HTML}{00A250}
\definecolor{ansi-green-intense}{HTML}{007427}
\definecolor{ansi-yellow}{HTML}{DDB62B}
\definecolor{ansi-yellow-intense}{HTML}{B27D12}
\definecolor{ansi-blue}{HTML}{208FFB}
\definecolor{ansi-blue-intense}{HTML}{0065CA}
\definecolor{ansi-magenta}{HTML}{D160C4}
\definecolor{ansi-magenta-intense}{HTML}{A03196}
\definecolor{ansi-cyan}{HTML}{60C6C8}
\definecolor{ansi-cyan-intense}{HTML}{258F8F}
\definecolor{ansi-white}{HTML}{C5C1B4}
\definecolor{ansi-white-intense}{HTML}{A1A6B2}
\definecolor{ansi-default-inverse-fg}{HTML}{FFFFFF}
\definecolor{ansi-default-inverse-bg}{HTML}{000000}

% Define an environment for non-plain-text code cell outputs (e.g. images)
\newbox\nbsphinxpromptbox
\makeatletter
\@ifpackagelater{sphinx}{2022/06/30}{% "later" means here "at least"
% In this branch Sphinx is at least at 5.1.0
\newenvironment{nbsphinxfancyoutput}{%
\sphinxcolorlet{VerbatimColor}{white}%
\sphinxcolorlet{VerbatimBorderColor}{nbsphinx-code-border}%
\spx@verb@boxes@fcolorbox@setup
    % for \sphinxincludegraphics check of maximal height
    \spx@image@maxheight         \textheight
    \advance\spx@image@maxheight -\spx@boxes@border@top
    \advance\spx@image@maxheight -\spx@boxes@padding@top
    \advance\spx@image@maxheight -\spx@boxes@padding@bottom
    \advance\spx@image@maxheight -\spx@boxes@border@bottom
    \advance\spx@image@maxheight -\baselineskip
\def\sphinxVerbatim@Before{\nbsphinxfancyaddprompt}%
\def\sphinxVerbatim@After {\@empty}%
\def\FrameCommand     {\sphinxVerbatim@FrameCommand}%
\def\FirstFrameCommand{\sphinxVerbatim@FirstFrameCommand}%
\def\MidFrameCommand  {\sphinxVerbatim@MidFrameCommand}%
\def\LastFrameCommand {\sphinxVerbatim@LastFrameCommand}%
\MakeFramed{\advance\hsize-\width\@totalleftmargin\z@\linewidth\hsize\@setminipage}%
\lineskip=1ex\lineskiplimit=1ex\raggedright%
}{\par\unskip\@minipagefalse\endMakeFramed}
\def\nbsphinxfancyaddprompt{\ifvoid\nbsphinxpromptbox\else
    \kern\spx@boxes@border@top\kern\spx@boxes@padding@top
    \copy\nbsphinxpromptbox
    \kern-\ht\nbsphinxpromptbox\kern-\dp\nbsphinxpromptbox
    \kern-\spx@boxes@padding@top\kern-\spx@boxes@border@top
    \nointerlineskip
    \fi}
}% End of Sphinx >= 5.1.0 branch
{% This branch for Sphinx < 5.1.0
\newenvironment{nbsphinxfancyoutput}{%
    % Avoid fatal error with framed.sty if graphics too long to fit on one page
    \let\sphinxincludegraphics\nbsphinxincludegraphics
    \nbsphinx@image@maxheight\textheight
    \advance\nbsphinx@image@maxheight -2\fboxsep   % default \fboxsep 3pt
    \advance\nbsphinx@image@maxheight -2\fboxrule  % default \fboxrule 0.4pt
    \advance\nbsphinx@image@maxheight -\baselineskip
\def\nbsphinxfcolorbox{\spx@fcolorbox{nbsphinx-code-border}{white}}%
\def\FrameCommand{\nbsphinxfcolorbox\nbsphinxfancyaddprompt\@empty}%
\def\FirstFrameCommand{\nbsphinxfcolorbox\nbsphinxfancyaddprompt\sphinxVerbatim@Continues}%
\def\MidFrameCommand{\nbsphinxfcolorbox\sphinxVerbatim@Continued\sphinxVerbatim@Continues}%
\def\LastFrameCommand{\nbsphinxfcolorbox\sphinxVerbatim@Continued\@empty}%
\MakeFramed{\advance\hsize-\width\@totalleftmargin\z@\linewidth\hsize\@setminipage}%
\lineskip=1ex\lineskiplimit=1ex\raggedright%
}{\par\unskip\@minipagefalse\endMakeFramed}
\def\nbsphinxfancyaddprompt{\ifvoid\nbsphinxpromptbox\else
    \kern\fboxrule\kern\fboxsep
    \copy\nbsphinxpromptbox
    \kern-\ht\nbsphinxpromptbox\kern-\dp\nbsphinxpromptbox
    \kern-\fboxsep\kern-\fboxrule\nointerlineskip
    \fi}
}% end of Sphinx < 5.1.0 branch
\makeatother
\newlength\nbsphinxcodecellspacing
\setlength{\nbsphinxcodecellspacing}{0pt}

% Define support macros for attaching opening and closing lines to notebooks
\newsavebox\nbsphinxbox
\makeatletter
\newcommand{\nbsphinxstartnotebook}[1]{%
    \par
    % measure needed space
    \setbox\nbsphinxbox\vtop{{#1\par}}
    % reserve some space at bottom of page, else start new page
    \needspace{\dimexpr2.5\baselineskip+\ht\nbsphinxbox+\dp\nbsphinxbox}
    % mimic vertical spacing from \section command
      \addpenalty\@secpenalty
      \@tempskipa 3.5ex \@plus 1ex \@minus .2ex\relax
      \addvspace\@tempskipa
      {\Large\@tempskipa\baselineskip
             \advance\@tempskipa-\prevdepth
             \advance\@tempskipa-\ht\nbsphinxbox
             \ifdim\@tempskipa>\z@
               \vskip \@tempskipa
             \fi}
    \unvbox\nbsphinxbox
    % if notebook starts with a \section, prevent it from adding extra space
    \@nobreaktrue\everypar{\@nobreakfalse\everypar{}}%
    % compensate the parskip which will get inserted by next paragraph
    \nobreak\vskip-\parskip
    % do not break here
    \nobreak
}% end of \nbsphinxstartnotebook

\newcommand{\nbsphinxstopnotebook}[1]{%
    \par
    % measure needed space
    \setbox\nbsphinxbox\vbox{{#1\par}}
    \nobreak % it updates page totals
    \dimen@\pagegoal
    \advance\dimen@-\pagetotal \advance\dimen@-\pagedepth
    \advance\dimen@-\ht\nbsphinxbox \advance\dimen@-\dp\nbsphinxbox
    \ifdim\dimen@<\z@
      % little space left
      \unvbox\nbsphinxbox
      \kern-.8\baselineskip
      \nobreak\vskip\z@\@plus1fil
      \penalty100
      \vskip\z@\@plus-1fil
      \kern.8\baselineskip
    \else
      \unvbox\nbsphinxbox
    \fi
}% end of \nbsphinxstopnotebook

% Ensure height of an included graphics fits in nbsphinxfancyoutput frame
% The Sphinx >= 5.1.0 version of nbsphinxfancyoutput does not use this macro
% as \sphinxincludegraphics is since Sphinx 2.0 similar and slightly better.
\newdimen\nbsphinx@image@maxheight % set in nbsphinxfancyoutput environment
\newcommand*{\nbsphinxincludegraphics}[2][]{%
    \gdef\spx@includegraphics@options{#1}%
    \setbox\spx@image@box\hbox{\includegraphics[#1,draft]{#2}}%
    \in@false
    \ifdim \wd\spx@image@box>\linewidth
      \g@addto@macro\spx@includegraphics@options{,width=\linewidth}%
      \in@true
    \fi
    % no rotation, no need to worry about depth
    \ifdim \ht\spx@image@box>\nbsphinx@image@maxheight
      \g@addto@macro\spx@includegraphics@options{,height=\nbsphinx@image@maxheight}%
      \in@true
    \fi
    \ifin@
      \g@addto@macro\spx@includegraphics@options{,keepaspectratio}%
    \fi
    \setbox\spx@image@box\box\voidb@x % clear memory
    \expandafter\includegraphics\expandafter[\spx@includegraphics@options]{#2}%
}% end of "\MakeFrame"-safe variant of \sphinxincludegraphics
\makeatother

\makeatletter
\renewcommand*\sphinx@verbatim@nolig@list{\do\'\do\`}
\begingroup
\catcode`'=\active
\let\nbsphinx@noligs\@noligs
\g@addto@macro\nbsphinx@noligs{\let'\PYGZsq}
\endgroup
\makeatother
\renewcommand*\sphinxbreaksbeforeactivelist{\do\<\do\"\do\'}
\renewcommand*\sphinxbreaksafteractivelist{\do\.\do\,\do\:\do\;\do\?\do\!\do\/\do\>\do\-}
\makeatletter
\fvset{codes*=\sphinxbreaksattexescapedchars\do\^\^\let\@noligs\nbsphinx@noligs}
\makeatother



\title{PyGenStability}
\date{Oct 19, 2023}
\release{}
\author{Alexis Arnaudon, Dominik Schindler}
\newcommand{\sphinxlogo}{\vbox{}}
\renewcommand{\releasename}{}
\makeindex
\begin{document}

\ifdefined\shorthandoff
  \ifnum\catcode`\=\string=\active\shorthandoff{=}\fi
  \ifnum\catcode`\"=\active\shorthandoff{"}\fi
\fi

\pagestyle{empty}
\sphinxmaketitle
\pagestyle{plain}
\sphinxtableofcontents
\pagestyle{normal}
\phantomsection\label{\detokenize{index::doc}}


\sphinxAtStartPar
This \sphinxcode{\sphinxupquote{python}} package is designed for multiscale community detection with Markov Stability (MS) analysis {[}1, 2{]} and allows researchers to identify robust network partitions at different resolutions. It implements several variants of the MS cost functions that are based on graph diffusion processes to explore the network (see illustration below). Whilst primarily built for MS, the internal architecture of \sphinxstyleemphasis{PyGenStability} has been designed to solve for a wide range of clustering cost functions since it is based on optimising the so\sphinxhyphen{}called generalized Markov Stability function {[}3{]}. To maximize the generalized Markov Stability cost function, \sphinxstyleemphasis{PyGenStability} provides a convenient \sphinxcode{\sphinxupquote{python}} interface for \sphinxcode{\sphinxupquote{C++}} implementations of Louvain {[}4{]} and Leiden {[}5{]} algorithms.
We further provide specific analysis tools to process and analyse the results from multiscale community detection, and to facilitate the automatic selection of robust partitions {[}6{]}. \sphinxstyleemphasis{PyGenStability} is accompanied by a software paper that further details the implementation, result analysis, benchmarks and applications {[}7{]}.

\sphinxhref{../artwork/diffusion\_schematic.png}{\sphinxincludegraphics[width=800\sphinxpxdimen,height=154\sphinxpxdimen]{{diffusion_schematic}.png}}


\chapter{Installation}
\label{\detokenize{index:installation}}
\sphinxAtStartPar
The wrapper uses Pybind11 \sphinxurl{https://github.com/pybind/pybind11} and the package can simply be installed by first cloning this repo with

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n}{git} \PYG{n}{clone} \PYG{o}{\PYGZhy{}}\PYG{o}{\PYGZhy{}}\PYG{n}{recurse}\PYG{o}{\PYGZhy{}}\PYG{n}{submodules} \PYG{n}{https}\PYG{p}{:}\PYG{o}{/}\PYG{o}{/}\PYG{n}{github}\PYG{o}{.}\PYG{n}{com}\PYG{o}{/}\PYG{n}{ImperialCollegeLondon}\PYG{o}{/}\PYG{n}{PyGenStability}\PYG{o}{.}\PYG{n}{git}
\end{sphinxVerbatim}

\sphinxAtStartPar
(if the \sphinxcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}recurse\sphinxhyphen{}submodules}} has not been used, just do \sphinxcode{\sphinxupquote{git submodule update \sphinxhyphen{}\sphinxhyphen{}init \sphinxhyphen{}\sphinxhyphen{}recursive}} to fetch the submodule with M. Schaub’s code).

\sphinxAtStartPar
Then, to install the package, simply run

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n}{pip} \PYG{n}{install} \PYG{o}{.}
\end{sphinxVerbatim}

\sphinxAtStartPar
using a fresh \sphinxcode{\sphinxupquote{virtualenv}} in python3 may be recommended to avoid conflict of python packages.

\sphinxAtStartPar
To use plotly for interactive plots in the browser, install this package with

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n}{pip} \PYG{n}{install} \PYG{o}{.}\PYG{p}{[}\PYG{n}{plotly}\PYG{p}{]}
\end{sphinxVerbatim}

\sphinxAtStartPar
To use a contrib module, with additional tools, run

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n}{pip} \PYG{n}{install} \PYG{o}{.}\PYG{p}{[}\PYG{n}{contrib}\PYG{p}{]}
\end{sphinxVerbatim}

\sphinxAtStartPar
To install all dependencies, run

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n}{pip} \PYG{n}{install} \PYG{o}{.}\PYG{p}{[}\PYG{n+nb}{all}\PYG{p}{]}
\end{sphinxVerbatim}


\chapter{Using the code}
\label{\detokenize{index:using-the-code}}
\sphinxAtStartPar
The code is simple to run with the default settings. We can input our graph (of type scipy.csgraph), run a scan in scales with a chosen Markov Stability constructor and plot the results in a summary figure presenting different partition quality measures across scales (values of MS cost function, number of communities, etc.) with an indication of optimal scales.

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{k+kn}{import} \PYG{n+nn}{pygenstability} \PYG{k}{as} \PYG{n+nn}{pgs}
\PYG{n}{results} \PYG{o}{=} \PYG{n}{pgs}\PYG{o}{.}\PYG{n}{run}\PYG{p}{(}\PYG{n}{graph}\PYG{p}{)}
\PYG{n}{pgs}\PYG{o}{.}\PYG{n}{plot\PYGZus{}scan}\PYG{p}{(}\PYG{n}{results}\PYG{p}{)}
\end{sphinxVerbatim}

\sphinxAtStartPar
Although it is enforced in the code, it is advised to set environment variables

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n}{export} \PYG{n}{OPENBLAS\PYGZus{}NUM\PYGZus{}THREADS}\PYG{o}{=}\PYG{l+m+mi}{1}
\PYG{n}{export} \PYG{n}{OMP\PYGZus{}NUM\PYGZus{}THREADS}\PYG{o}{=}\PYG{l+m+mi}{1}
\PYG{n}{export} \PYG{n}{NUMEXPR\PYGZus{}MAX\PYGZus{}THREADS}\PYG{o}{=}\PYG{l+m+mi}{1}
\end{sphinxVerbatim}

\sphinxAtStartPar
to ensure numpy does not use multi\sphinxhyphen{}threadings, which may clash with the parallelisation and slow down the computation.

\sphinxAtStartPar
There are a variety of further choices that users can make that will impact the partitioning, including:
\begin{itemize}
\item {} 
\sphinxAtStartPar
Constructor: Generalized Markov Stability requires the user to input a quality matrix and associated null models. We provide an object\sphinxhyphen{}oriented module to write user\sphinxhyphen{}defined constructors for these objects, with several already implemented (see \sphinxcode{\sphinxupquote{pygenstability/constructors.py}} for some classic examples).

\item {} 
\sphinxAtStartPar
Generalized Markov Stability maximizers: To maximize the NP\sphinxhyphen{}hard optimal generalized Markov Stability we interface with two algorithms: (i) Louvain and (ii) Leiden.

\end{itemize}

\sphinxAtStartPar
While Louvain is defined as the default due to its familiarity within the research community, Leiden is known to produce better partitions and can be used by specifying the run function.

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n}{results} \PYG{o}{=} \PYG{n}{pgs}\PYG{o}{.}\PYG{n}{run}\PYG{p}{(}\PYG{n}{graph}\PYG{p}{,} \PYG{n}{method}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{leiden}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{)}
\end{sphinxVerbatim}

\sphinxAtStartPar
There are also additional post\sphinxhyphen{}processing and analysis functions, including:
\begin{itemize}
\item {} 
\sphinxAtStartPar
Plotting via matplotlib and plotly (interactive).

\item {} 
\sphinxAtStartPar
Automated optimal scale selection.

\end{itemize}

\sphinxAtStartPar
Optimal scale selection {[}6{]} is performed by default with the run function but can be repeated with different parameters if needed, see \sphinxcode{\sphinxupquote{pygenstability/optimal\_scales.py}}. To reduce noise, e.g., one can increase the parameter values for \sphinxcode{\sphinxupquote{block\_size}} and \sphinxcode{\sphinxupquote{window\_size}}. The optimal network partitions can then be plotted given a NetworkX nx\_graph.

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n}{results} \PYG{o}{=} \PYG{n}{pgs}\PYG{o}{.}\PYG{n}{identify\PYGZus{}optimal\PYGZus{}scales}\PYG{p}{(}\PYG{n}{results}\PYG{p}{,} \PYG{n}{block\PYGZus{}size}\PYG{o}{=}\PYG{l+m+mi}{10}\PYG{p}{,} \PYG{n}{window\PYGZus{}size}\PYG{o}{=}\PYG{l+m+mi}{5}\PYG{p}{)}
\PYG{n}{pgs}\PYG{o}{.}\PYG{n}{plot\PYGZus{}optimal\PYGZus{}partitions}\PYG{p}{(}\PYG{n}{nx\PYGZus{}graph}\PYG{p}{,} \PYG{n}{results}\PYG{p}{)}
\end{sphinxVerbatim}


\chapter{Constructors}
\label{\detokenize{index:constructors}}
\sphinxAtStartPar
We provide an object\sphinxhyphen{}oriented module for constructing quality matrices and null models in \sphinxcode{\sphinxupquote{pygenstability/constructors.py}}. Various constructors are implemented for different types of graphs:
\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{linearized}} based on linearized MS for large undirected weighted graphs {[}2{]}

\item {} 
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{continuous\_combinatorial}} based on combinatorial Laplacian for undirected weighted graphs {[}2{]}

\item {} 
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{continuous\_normalized}} based on random\sphinxhyphen{}walk normalized Laplacians for undirected weighted graphs {[}2{]}

\item {} 
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{signed\_modularity}} based on signed modularity for large signed graphs {[}8{]}

\item {} 
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{signed\_combinatorial}} based on signed combinatorial Laplacian for signed graphs {[}3{]}

\item {} 
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{directed}} based on random\sphinxhyphen{}walk Laplacian with teleportation for directed weighted graphs {[}2{]}

\item {} 
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{linearized\_directed}} based on random\sphinxhyphen{}walk Laplacian with teleportation for large directed weighted graphs

\end{itemize}

\sphinxAtStartPar
For the computationally efficient analysis of \sphinxstylestrong{large} graphs, we recommend using the \sphinxcode{\sphinxupquote{linearized}}, \sphinxcode{\sphinxupquote{linearized\_directed}} or \sphinxcode{\sphinxupquote{signed\_modularity}} constructors instead of \sphinxcode{\sphinxupquote{continuous\_combinatorial}}, \sphinxcode{\sphinxupquote{continuous\_normalized}}, \sphinxcode{\sphinxupquote{directed}} or \sphinxcode{\sphinxupquote{signed\_combinatorial}} that rely on the computation of matrix exponentials.

\sphinxAtStartPar
For those of you that wish to implement their own constructor, you will need to design a function with the following properties:
\begin{itemize}
\item {} 
\sphinxAtStartPar
take a scipy.csgraph \sphinxcode{\sphinxupquote{graph}} and a float \sphinxcode{\sphinxupquote{time}} as argument

\item {} 
\sphinxAtStartPar
return a \sphinxcode{\sphinxupquote{quality\_matrix}} (sparse scipy matrix) and a \sphinxcode{\sphinxupquote{null\_model}} (multiples of two, in a numpy array)

\end{itemize}


\chapter{Contributors}
\label{\detokenize{index:contributors}}\begin{itemize}
\item {} 
\sphinxAtStartPar
Alexis Arnaudon, GitHub: \sphinxcode{\sphinxupquote{arnaudon \textless{}https://github.com/arnaudon\textgreater{}}}

\item {} 
\sphinxAtStartPar
Robert Peach, GitHub: \sphinxcode{\sphinxupquote{peach\sphinxhyphen{}lucien \textless{}https://github.com/peach\sphinxhyphen{}lucien\textgreater{}}}

\item {} 
\sphinxAtStartPar
Dominik Schindler, GitHub: \sphinxcode{\sphinxupquote{d\sphinxhyphen{}schindler \textless{}https://github.com/d\sphinxhyphen{}schindler\textgreater{}}}

\end{itemize}

\sphinxAtStartPar
We always look out for individuals that are interested in contributing to this open\sphinxhyphen{}source project. Even if you are just using \sphinxstyleemphasis{PyGenStability} and made some minor updates, we would be interested in your input.


\chapter{Cite}
\label{\detokenize{index:cite}}
\sphinxAtStartPar
Please cite our paper if you use this code in your own work:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n+nd}{@article}\PYG{p}{\PYGZob{}}\PYG{n}{pygenstability}\PYG{p}{,}
  \PYG{n}{author} \PYG{o}{=} \PYG{p}{\PYGZob{}}\PYG{n}{Arnaudon}\PYG{p}{,} \PYG{n}{Alexis} \PYG{o+ow}{and} \PYG{n}{Schindler}\PYG{p}{,} \PYG{n}{Dominik} \PYG{n}{J}\PYG{o}{.} \PYG{o+ow}{and} \PYG{n}{Peach}\PYG{p}{,} \PYG{n}{Robert} \PYG{n}{L}\PYG{o}{.} \PYG{o+ow}{and} \PYG{n}{Gosztolai}\PYG{p}{,} \PYG{n}{Adam} \PYG{o+ow}{and} \PYG{n}{Hodges}\PYG{p}{,} \PYG{n}{Maxwell} \PYG{o+ow}{and} \PYG{n}{Schaub}\PYG{p}{,} \PYG{n}{Michael} \PYG{n}{T}\PYG{o}{.} \PYG{o+ow}{and} \PYG{n}{Barahona}\PYG{p}{,} \PYG{n}{Mauricio}\PYG{p}{\PYGZcb{}}\PYG{p}{,}
  \PYG{n}{title} \PYG{o}{=} \PYG{p}{\PYGZob{}}\PYG{n}{PyGenStability}\PYG{p}{:} \PYG{n}{Multiscale} \PYG{n}{community} \PYG{n}{detection} \PYG{k}{with} \PYG{n}{generalized} \PYG{n}{Markov} \PYG{n}{Stability}\PYG{p}{\PYGZcb{}}\PYG{p}{,}
  \PYG{n}{publisher} \PYG{o}{=} \PYG{p}{\PYGZob{}}\PYG{n}{arXiv}\PYG{p}{\PYGZcb{}}\PYG{p}{,}
  \PYG{n}{year} \PYG{o}{=} \PYG{p}{\PYGZob{}}\PYG{l+m+mi}{2023}\PYG{p}{\PYGZcb{}}\PYG{p}{,}
  \PYG{n}{doi} \PYG{o}{=} \PYG{p}{\PYGZob{}}\PYG{l+m+mf}{10.48550}\PYG{o}{/}\PYG{n}{ARXIV}\PYG{l+m+mf}{.2303}\PYG{l+m+mf}{.05385}\PYG{p}{\PYGZcb{}}\PYG{p}{,}
  \PYG{n}{url} \PYG{o}{=} \PYG{p}{\PYGZob{}}\PYG{n}{https}\PYG{p}{:}\PYG{o}{/}\PYG{o}{/}\PYG{n}{arxiv}\PYG{o}{.}\PYG{n}{org}\PYG{o}{/}\PYG{n+nb}{abs}\PYG{o}{/}\PYG{l+m+mf}{2303.05385}\PYG{p}{\PYGZcb{}}
\PYG{p}{\PYGZcb{}}
\end{sphinxVerbatim}

\sphinxAtStartPar
The original paper for Markov Stability can also be cited as:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n+nd}{@article}\PYG{p}{\PYGZob{}}\PYG{n}{delvenne2010stability}\PYG{p}{,}
  \PYG{n}{title}\PYG{o}{=}\PYG{p}{\PYGZob{}}\PYG{n}{Stability} \PYG{n}{of} \PYG{n}{graph} \PYG{n}{communities} \PYG{n}{across} \PYG{n}{time} \PYG{n}{scales}\PYG{p}{\PYGZcb{}}\PYG{p}{,}
  \PYG{n}{author}\PYG{o}{=}\PYG{p}{\PYGZob{}}\PYG{n}{Delvenne}\PYG{p}{,} \PYG{n}{J}\PYG{o}{\PYGZhy{}}\PYG{n}{C} \PYG{o+ow}{and} \PYG{n}{Yaliraki}\PYG{p}{,} \PYG{n}{Sophia} \PYG{n}{N} \PYG{o+ow}{and} \PYG{n}{Barahona}\PYG{p}{,} \PYG{n}{Mauricio}\PYG{p}{\PYGZcb{}}\PYG{p}{,}
  \PYG{n}{journal}\PYG{o}{=}\PYG{p}{\PYGZob{}}\PYG{n}{Proceedings} \PYG{n}{of} \PYG{n}{the} \PYG{n}{National} \PYG{n}{Academy} \PYG{n}{of} \PYG{n}{Sciences}\PYG{p}{\PYGZcb{}}\PYG{p}{,}
  \PYG{n}{volume}\PYG{o}{=}\PYG{p}{\PYGZob{}}\PYG{l+m+mi}{107}\PYG{p}{\PYGZcb{}}\PYG{p}{,}
  \PYG{n}{number}\PYG{o}{=}\PYG{p}{\PYGZob{}}\PYG{l+m+mi}{29}\PYG{p}{\PYGZcb{}}\PYG{p}{,}
  \PYG{n}{pages}\PYG{o}{=}\PYG{p}{\PYGZob{}}\PYG{l+m+mi}{12755}\PYG{o}{\PYGZhy{}}\PYG{o}{\PYGZhy{}}\PYG{l+m+mi}{12760}\PYG{p}{\PYGZcb{}}\PYG{p}{,}
  \PYG{n}{year}\PYG{o}{=}\PYG{p}{\PYGZob{}}\PYG{l+m+mi}{2010}\PYG{p}{\PYGZcb{}}\PYG{p}{,}
  \PYG{n}{publisher}\PYG{o}{=}\PYG{p}{\PYGZob{}}\PYG{n}{National} \PYG{n}{Acad} \PYG{n}{Sciences}\PYG{p}{\PYGZcb{}}
\PYG{p}{\PYGZcb{}}
\end{sphinxVerbatim}


\chapter{Run example}
\label{\detokenize{index:run-example}}
\sphinxAtStartPar
In the \sphinxcode{\sphinxupquote{example}} folder, a demo script with a stochastic block model can be tried with

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n}{python} \PYG{n}{simple\PYGZus{}example}\PYG{o}{.}\PYG{n}{py}
\end{sphinxVerbatim}

\sphinxAtStartPar
or using the click app:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{o}{.}\PYG{o}{/}\PYG{n}{run\PYGZus{}simple\PYGZus{}example}\PYG{o}{.}\PYG{n}{sh}
\end{sphinxVerbatim}

\sphinxAtStartPar
Other examples can be found as jupyter\sphinxhyphen{}notebooks in the \sphinxcode{\sphinxupquote{examples/}} directory, including:
\begin{itemize}
\item {} 
\sphinxAtStartPar
Example 1: Undirected SBM

\item {} 
\sphinxAtStartPar
Example 2: Multiscale SBM

\item {} 
\sphinxAtStartPar
Example 3: Directed networks

\item {} 
\sphinxAtStartPar
Example 4: Custom constructors

\item {} 
\sphinxAtStartPar
Example 5: Hypergraphs

\item {} 
\sphinxAtStartPar
Example 6: Signed networks

\end{itemize}

\sphinxAtStartPar
Finally, we provide applications to real\sphinxhyphen{}world networks in the \sphinxcode{\sphinxupquote{examples/real\_examples/}} directory, including:
\begin{itemize}
\item {} 
\sphinxAtStartPar
Power grid network

\item {} 
\sphinxAtStartPar
Protein structures

\end{itemize}


\chapter{Our other available packages}
\label{\detokenize{index:our-other-available-packages}}
\sphinxAtStartPar
If you are interested in trying our other packages, see the below list:
\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxhref{https://github.com/barahona-research-group/GDR}{GDR} : Graph diffusion reclassification. A methodology for node classification using graph semi\sphinxhyphen{}supervised learning.

\item {} 
\sphinxAtStartPar
\sphinxhref{https://github.com/barahona-research-group/hcga}{hcga} : Highly comparative graph analysis. A graph analysis toolbox that performs massive feature extraction from a set of graphs, and applies supervised classification methods.

\item {} 
\sphinxAtStartPar
\sphinxhref{https://github.com/barahona-research-group/MultiscaleCentrality}{MSC} : MultiScale Centrality: A scale\sphinxhyphen{}dependent metric of node centrality.

\item {} 
\sphinxAtStartPar
\sphinxhref{https://github.com/barahona-research-group/DynGDim}{DynGDim} : Dynamic Graph Dimension: Computing the relative, local and global dimension of complex networks.

\item {} 
\sphinxAtStartPar
\sphinxhref{https://github.com/barahona-research-group/RMST}{RMST} : Relaxed Minimum Spanning Tree: Computing the relaxed minimum spanning tree to sparsify networks whilst retaining dynamic structure.

\item {} 
\sphinxAtStartPar
\sphinxhref{https://github.com/barahona-research-group/StEP}{StEP} : Spatial\sphinxhyphen{}temporal Epidemiological Proximity: Characterising contact in disease outbreaks via a network model of spatial\sphinxhyphen{}temporal proximity.

\end{itemize}


\chapter{References}
\label{\detokenize{index:references}}
\sphinxAtStartPar
{[}1{]} J.\sphinxhyphen{}C. Delvenne, S. N. Yaliraki, and M. Barahona, ‘Stability of graph communities across time scales’, \sphinxstyleemphasis{Proceedings of the National Academy of Sciences}, vol. 107, no. 29, pp. 12755\textendash{}12760, Jul. 2010, doi: 10.1073/pnas.0903215107.

\sphinxAtStartPar
{[}2{]} R. Lambiotte, J.\sphinxhyphen{}C. Delvenne, and M. Barahona, ‘Random Walks, Markov Processes and the Multiscale Modular Organization of Complex Networks’, \sphinxstyleemphasis{IEEE Trans. Netw. Sci. Eng.}, vol. 1, no. 2, pp. 76\textendash{}90, Jul. 2014, doi: 10.1109/TNSE.2015.2391998.

\sphinxAtStartPar
{[}3{]} M. T. Schaub, J.\sphinxhyphen{}C. Delvenne, R. Lambiotte, and M. Barahona, ‘Multiscale dynamical embeddings of complex networks’, \sphinxstyleemphasis{Phys. Rev. E}, vol. 99, no. 6, Jun. 2019, doi: 10.1103/PhysRevE.99.062308.

\sphinxAtStartPar
{[}4{]} V. D. Blondel, J.\sphinxhyphen{}L. Guillaume, R. Lambiotte, and E. Lefebvre, ‘Fast unfolding of communities in large networks’, \sphinxstyleemphasis{J. Stat. Mech.}, vol. 2008, no. 10, Oct. 2008, doi: 10.1088/1742\sphinxhyphen{}5468/2008/10/p10008.

\sphinxAtStartPar
{[}5{]} V. A. Traag, L. Waltman, and N. J. van Eck, ‘From Louvain to Leiden: guaranteeing well\sphinxhyphen{}connected communities’, \sphinxstyleemphasis{Sci Rep}, vol. 9, no. 1, p. 5233, Mar. 2019, doi: 10.1038/s41598\sphinxhyphen{}019\sphinxhyphen{}41695\sphinxhyphen{}z.

\sphinxAtStartPar
{[}6{]} D. J. Schindler, J. Clarke, and M. Barahona, ‘Multiscale Mobility Patterns and the Restriction of Human Movement’, \sphinxstyleemphasis{Royal Society Open Science}, vol. 10, no. 10, p. 230405, Oct. 2023, doi: 10.1098/rsos.230405.

\sphinxAtStartPar
{[}7{]} A. Arnaudon, D. J. Schindler, R. L. Peach, A. Gosztolai, M. Hodges, M. T. Schaub, and M. Barahona, ‘PyGenStability: Multiscale community detection with generalized Markov Stability‘, \sphinxstyleemphasis{arXiv pre\sphinxhyphen{}print}, Mar. 2023, doi: 10.48550/arXiv.2303.05385.

\sphinxAtStartPar
{[}8{]} S. Gómez, P. Jensen, and A. Arenas, ‘Analysis of community structure in networks of correlated data‘. \sphinxstyleemphasis{Physical Review E}, vol. 80, no. 1, p. 016114, Jul. 2009, doi: 10.1103/PhysRevE.80.016114.


\chapter{Licence}
\label{\detokenize{index:licence}}
\sphinxAtStartPar
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

\sphinxAtStartPar
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

\sphinxAtStartPar
You should have received a copy of the GNU General Public License along with this program. If not, see \sphinxurl{http://www.gnu.org/licenses/}.


\chapter{API documentation}
\label{\detokenize{index:api-documentation}}
\sphinxAtStartPar
Documentation of the API of \sphinxstyleemphasis{PyGenStability}.

\sphinxstepscope


\section{PyGenStability module}
\label{\detokenize{pygenstability:module-pygenstability.pygenstability}}\label{\detokenize{pygenstability:pygenstability-module}}\label{\detokenize{pygenstability::doc}}\index{module@\spxentry{module}!pygenstability.pygenstability@\spxentry{pygenstability.pygenstability}}\index{pygenstability.pygenstability@\spxentry{pygenstability.pygenstability}!module@\spxentry{module}}
\sphinxAtStartPar
PyGenStability code to solve generalized Markov Stability including Markov stability.

\sphinxAtStartPar
The generalized Markov Stability is of the form
\begin{equation*}
\begin{split}Q_{gen}(t,H) = \mathrm{Tr} \left [H^T \left (F(t)-\sum_{k=1}^m v_{2k-1} v_{2k}^T\right)H\right]\end{split}
\end{equation*}
\sphinxAtStartPar
where \(F(t)\) is the quality matrix and \(v_k\) are null model vectors.
The choice of the quality matrix and null model vectors are arbitrary in the generalized
Markov Stability setting, and can be parametrised via built\sphinxhyphen{}in constructors, or specified by
the user via the constructor module.
\index{run() (in module pygenstability.pygenstability)@\spxentry{run()}\spxextra{in module pygenstability.pygenstability}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{pygenstability:pygenstability.pygenstability.run}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{pygenstability.pygenstability.}}\sphinxbfcode{\sphinxupquote{run}}}{\emph{\DUrole{n}{graph}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{constructor}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}linearized\textquotesingle{}}}, \emph{\DUrole{n}{min\_scale}\DUrole{o}{=}\DUrole{default_value}{\sphinxhyphen{}2.0}}, \emph{\DUrole{n}{max\_scale}\DUrole{o}{=}\DUrole{default_value}{0.5}}, \emph{\DUrole{n}{n\_scale}\DUrole{o}{=}\DUrole{default_value}{20}}, \emph{\DUrole{n}{log\_scale}\DUrole{o}{=}\DUrole{default_value}{True}}, \emph{\DUrole{n}{scales}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{n\_tries}\DUrole{o}{=}\DUrole{default_value}{100}}, \emph{\DUrole{n}{with\_NVI}\DUrole{o}{=}\DUrole{default_value}{True}}, \emph{\DUrole{n}{n\_NVI}\DUrole{o}{=}\DUrole{default_value}{20}}, \emph{\DUrole{n}{with\_postprocessing}\DUrole{o}{=}\DUrole{default_value}{True}}, \emph{\DUrole{n}{with\_ttprime}\DUrole{o}{=}\DUrole{default_value}{True}}, \emph{\DUrole{n}{with\_spectral\_gap}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{exp\_comp\_mode}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}spectral\textquotesingle{}}}, \emph{\DUrole{n}{result\_file}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}results.pkl\textquotesingle{}}}, \emph{\DUrole{n}{n\_workers}\DUrole{o}{=}\DUrole{default_value}{4}}, \emph{\DUrole{n}{tqdm\_disable}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{with\_optimal\_scales}\DUrole{o}{=}\DUrole{default_value}{True}}, \emph{\DUrole{n}{optimal\_scales\_kwargs}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{method}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}louvain\textquotesingle{}}}, \emph{\DUrole{n}{constructor\_kwargs}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
This is the main function to compute graph clustering across scales with Markov Stability.

\sphinxAtStartPar
This function needs a graph object  as an adjacency matrix encoded with scipy.csgraph.
The default settings will provide a fast and generic run with linearized Markov Stability,
which corresponds to modularity with a scale parameter. Other built\sphinxhyphen{}in constructors are
available to perform Markov Stability with matrix exponential computations. Custom constructors
can be added via the constructor module.
Additional parameters can be used to set the range and number of scales, number of trials for
generalized Markov Stability optimisation, with Louvain or Leiden algorithm.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{graph}} (\sphinxstyleliteralemphasis{\sphinxupquote{scipy.csgraph}}) \textendash{} graph to cluster, if None, the constructor cannot be a str

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{constructor}} (\sphinxstyleliteralemphasis{\sphinxupquote{str/function}}) \textendash{} name of the generalized Markov Stability constructor,
or custom constructor function. It must have two arguments, graph and scale.

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{min\_scale}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} minimum Markov scale

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{max\_scale}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} maximum Markov scale

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n\_scale}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of scale steps

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{log\_scale}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} use linear or log scales for scales

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{scales}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} custom scale vector, if provided, it will override the other scale arguments

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n\_tries}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of generalized Markov Stability optimisation evaluations

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{with\_NVI}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} compute NVI(t) between generalized Markov Stability optimisations
at each scale t

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n\_NVI}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of randomly chosen generalized Markov Stability optimisations
to estimate NVI

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{with\_postprocessing}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} apply the final postprocessing step

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{with\_ttprime}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} compute the NVI(t,tprime) matrix to compare scales t and tprime

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{with\_spectral\_gap}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} normalise scale by spectral gap

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{exp\_comp\_mode}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} mode to compute matrix exponential, can be expm or spectral

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{result\_file}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} path to the result file

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n\_workers}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of workers for multiprocessing

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{tqdm\_disable}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} disable progress bars

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{with\_optimal\_scales}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} apply optimal scale selection algorithm

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{optimal\_scales\_kwargs}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} kwargs to pass to optimal scale selection, see
optimal\_scale module.

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{method}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} optimiation method, louvain or leiden

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{constructor\_kwargs}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} additional kwargs to pass to constructor prepare method

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\begin{description}
\sphinxlineitem{Results dict with the following entries}\begin{itemize}
\item {} 
\sphinxAtStartPar
’run\_params’: dict with parameters used to run the code

\item {} 
\sphinxAtStartPar
’scales’: scales of the scan

\item {} 
\sphinxAtStartPar
’number\_of\_communities’: number of communities at each scale

\item {} 
\sphinxAtStartPar
’community\_id’: community node labels at each scale

\item {} 
\sphinxAtStartPar
’NVI’: NVI at each scale

\item {} 
\sphinxAtStartPar
’ttprime’: ttprime matrix

\end{itemize}

\end{description}


\end{description}\end{quote}

\end{fulllineitems}

\index{evaluate\_NVI() (in module pygenstability.pygenstability)@\spxentry{evaluate\_NVI()}\spxextra{in module pygenstability.pygenstability}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{pygenstability:pygenstability.pygenstability.evaluate_NVI}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{pygenstability.pygenstability.}}\sphinxbfcode{\sphinxupquote{evaluate\_NVI}}}{\emph{\DUrole{n}{index\_pair}}, \emph{\DUrole{n}{partitions}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Evaluations of Normalized Variation of Information (NVI).

\sphinxAtStartPar
NVI is defined for two partitions \(p1\) and \(p2\) as:
\begin{equation*}
\begin{split}NVI = \frac{E(p1) + E(p2) - 2MI(p1, p2)}{JE(p1,p2)}\end{split}
\end{equation*}
\sphinxAtStartPar
where \(E\) is the entropy, \(JE\) the joint entropy
and \(MI\) the mutual information.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{index\_pair}} (\sphinxstyleliteralemphasis{\sphinxupquote{list}}) \textendash{} list of two indices to select pairs of partitions

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{partitions}} (\sphinxstyleliteralemphasis{\sphinxupquote{list}}) \textendash{} list of partitions

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
float, Normalized Variation Information

\end{description}\end{quote}

\end{fulllineitems}


\sphinxstepscope


\section{Constructors module}
\label{\detokenize{constructors:module-pygenstability.constructors}}\label{\detokenize{constructors:constructors-module}}\label{\detokenize{constructors::doc}}\index{module@\spxentry{module}!pygenstability.constructors@\spxentry{pygenstability.constructors}}\index{pygenstability.constructors@\spxentry{pygenstability.constructors}!module@\spxentry{module}}
\sphinxAtStartPar
Module to create constructors of quality matrix and null models.

\sphinxAtStartPar
The generalized Markov Stability is given as
\begin{equation*}
\begin{split}Q_{gen}(t,H) = \mathrm{Tr} \left [H^T \left (F(t)-\sum_{k=1}^m v_{2k-1} v_{2k}^T\right)H\right]\end{split}
\end{equation*}
\sphinxAtStartPar
where \(F(t)\) is the quality matrix and \(v_k\) are null model vectors.

\sphinxAtStartPar
In the following we denote by \(A\) the adjacency matrix of a graph with \(N\) nodes and
\(M\) edges. The out\sphinxhyphen{}degree of the graph is given by \(d=A\boldsymbol{1}\), where
\(\boldsymbol{1}\) is the vector of ones, and we denote the diagonal degree matrix by
\(D=\mathrm{diag}(d)\).
\index{load\_constructor() (in module pygenstability.constructors)@\spxentry{load\_constructor()}\spxextra{in module pygenstability.constructors}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{constructors:pygenstability.constructors.load_constructor}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{pygenstability.constructors.}}\sphinxbfcode{\sphinxupquote{load\_constructor}}}{\emph{\DUrole{n}{constructor}}, \emph{\DUrole{n}{graph}}, \emph{\DUrole{o}{**}\DUrole{n}{kwargs}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Load a constructor from its name, or as a custom Constructor class.

\end{fulllineitems}

\index{Constructor (class in pygenstability.constructors)@\spxentry{Constructor}\spxextra{class in pygenstability.constructors}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{constructors:pygenstability.constructors.Constructor}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{  }}}\sphinxcode{\sphinxupquote{pygenstability.constructors.}}\sphinxbfcode{\sphinxupquote{Constructor}}}{\emph{\DUrole{n}{graph}}, \emph{\DUrole{n}{with\_spectral\_gap}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{exp\_comp\_mode}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}spectral\textquotesingle{}}}, \emph{\DUrole{o}{**}\DUrole{n}{kwargs}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Parent class for generalized Markov Stability constructor.

\sphinxAtStartPar
This class encodes generalized Markov Stability through the quality matrix and null models.
Use the method prepare to load and compute scale independent quantities, and the method get\_data
to return quality matrix, null model, and possible global shift.

\sphinxAtStartPar
The constructor calls the prepare method upon initialisation.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{graph}} (\sphinxstyleliteralemphasis{\sphinxupquote{csgraph}}) \textendash{} graph for which to run clustering

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{with\_spectral\_gap}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} set to True to use spectral gap to rescale

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kwargs}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} any other properties to pass to the constructor.

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{exp\_comp\_mode}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} mode to compute matrix exponential, can be expm or spectral

\end{itemize}

\end{description}\end{quote}
\index{prepare() (pygenstability.constructors.Constructor method)@\spxentry{prepare()}\spxextra{pygenstability.constructors.Constructor method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{constructors:pygenstability.constructors.Constructor.prepare}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{prepare}}}{\emph{\DUrole{o}{**}\DUrole{n}{kwargs}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Prepare the constructor with non\sphinxhyphen{}scale dependent computations.

\end{fulllineitems}

\index{get\_data() (pygenstability.constructors.Constructor method)@\spxentry{get\_data()}\spxextra{pygenstability.constructors.Constructor method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{constructors:pygenstability.constructors.Constructor.get_data}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_data}}}{\emph{\DUrole{n}{scale}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Return quality and null model at given scale as well as global shift (or None).

\sphinxAtStartPar
User has to define the \_get\_data so we can enure numpy does not use multiple threads

\end{fulllineitems}


\end{fulllineitems}

\index{constructor\_linearized (class in pygenstability.constructors)@\spxentry{constructor\_linearized}\spxextra{class in pygenstability.constructors}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{constructors:pygenstability.constructors.constructor_linearized}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{  }}}\sphinxcode{\sphinxupquote{pygenstability.constructors.}}\sphinxbfcode{\sphinxupquote{constructor\_linearized}}}{\emph{\DUrole{n}{graph}}, \emph{\DUrole{n}{with\_spectral\_gap}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{exp\_comp\_mode}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}spectral\textquotesingle{}}}, \emph{\DUrole{o}{**}\DUrole{n}{kwargs}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Constructor for continuous linearized Markov Stability.

\sphinxAtStartPar
The quality matrix is:
\begin{equation*}
\begin{split}F(t) = t\frac{A}{2M},\end{split}
\end{equation*}
\sphinxAtStartPar
and the associated null model is \(v_1=v_2=\frac{d}{2M}\).

\sphinxAtStartPar
The constructor calls the prepare method upon initialisation.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{graph}} (\sphinxstyleliteralemphasis{\sphinxupquote{csgraph}}) \textendash{} graph for which to run clustering

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{with\_spectral\_gap}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} set to True to use spectral gap to rescale

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kwargs}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} any other properties to pass to the constructor.

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{exp\_comp\_mode}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} mode to compute matrix exponential, can be expm or spectral

\end{itemize}

\end{description}\end{quote}
\index{prepare() (pygenstability.constructors.constructor\_linearized method)@\spxentry{prepare()}\spxextra{pygenstability.constructors.constructor\_linearized method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{constructors:pygenstability.constructors.constructor_linearized.prepare}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{prepare}}}{\emph{\DUrole{o}{**}\DUrole{n}{kwargs}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Prepare the constructor with non\sphinxhyphen{}scale dependent computations.

\end{fulllineitems}


\end{fulllineitems}

\index{constructor\_continuous\_combinatorial (class in pygenstability.constructors)@\spxentry{constructor\_continuous\_combinatorial}\spxextra{class in pygenstability.constructors}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{constructors:pygenstability.constructors.constructor_continuous_combinatorial}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{  }}}\sphinxcode{\sphinxupquote{pygenstability.constructors.}}\sphinxbfcode{\sphinxupquote{constructor\_continuous\_combinatorial}}}{\emph{\DUrole{n}{graph}}, \emph{\DUrole{n}{with\_spectral\_gap}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{exp\_comp\_mode}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}spectral\textquotesingle{}}}, \emph{\DUrole{o}{**}\DUrole{n}{kwargs}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Constructor for continuous combinatorial Markov Stability.

\sphinxAtStartPar
The quality matrix is:
\begin{equation*}
\begin{split}F(t) = \Pi\exp(-Lt)\end{split}
\end{equation*}
\sphinxAtStartPar
where \(L=D-A\) is the combinatorial Laplacian and \(\Pi=\mathrm{diag}(\pi)\),
with null model \(v_1=v_2=\pi=\frac{\boldsymbol{1}}{N}\).

\sphinxAtStartPar
The constructor calls the prepare method upon initialisation.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{graph}} (\sphinxstyleliteralemphasis{\sphinxupquote{csgraph}}) \textendash{} graph for which to run clustering

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{with\_spectral\_gap}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} set to True to use spectral gap to rescale

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kwargs}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} any other properties to pass to the constructor.

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{exp\_comp\_mode}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} mode to compute matrix exponential, can be expm or spectral

\end{itemize}

\end{description}\end{quote}
\index{prepare() (pygenstability.constructors.constructor\_continuous\_combinatorial method)@\spxentry{prepare()}\spxextra{pygenstability.constructors.constructor\_continuous\_combinatorial method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{constructors:pygenstability.constructors.constructor_continuous_combinatorial.prepare}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{prepare}}}{\emph{\DUrole{o}{**}\DUrole{n}{kwargs}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Prepare the constructor with non\sphinxhyphen{}scale dependent computations.

\end{fulllineitems}


\end{fulllineitems}

\index{constructor\_continuous\_normalized (class in pygenstability.constructors)@\spxentry{constructor\_continuous\_normalized}\spxextra{class in pygenstability.constructors}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{constructors:pygenstability.constructors.constructor_continuous_normalized}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{  }}}\sphinxcode{\sphinxupquote{pygenstability.constructors.}}\sphinxbfcode{\sphinxupquote{constructor\_continuous\_normalized}}}{\emph{\DUrole{n}{graph}}, \emph{\DUrole{n}{with\_spectral\_gap}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{exp\_comp\_mode}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}spectral\textquotesingle{}}}, \emph{\DUrole{o}{**}\DUrole{n}{kwargs}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Constructor for continuous normalized Markov Stability.

\sphinxAtStartPar
The quality matrix is:
\begin{equation*}
\begin{split}F(t) = \Pi\exp(-Lt)\end{split}
\end{equation*}
\sphinxAtStartPar
where \(L=D^{-1}(D-A)\) is the random\sphinxhyphen{}walk normalized Laplacian and
\(\Pi=\mathrm{diag}(\pi)\) with null model \(v_1=v_2=\pi=\frac{d}{2M}\).

\sphinxAtStartPar
The constructor calls the prepare method upon initialisation.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{graph}} (\sphinxstyleliteralemphasis{\sphinxupquote{csgraph}}) \textendash{} graph for which to run clustering

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{with\_spectral\_gap}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} set to True to use spectral gap to rescale

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kwargs}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} any other properties to pass to the constructor.

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{exp\_comp\_mode}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} mode to compute matrix exponential, can be expm or spectral

\end{itemize}

\end{description}\end{quote}
\index{prepare() (pygenstability.constructors.constructor\_continuous\_normalized method)@\spxentry{prepare()}\spxextra{pygenstability.constructors.constructor\_continuous\_normalized method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{constructors:pygenstability.constructors.constructor_continuous_normalized.prepare}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{prepare}}}{\emph{\DUrole{o}{**}\DUrole{n}{kwargs}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Prepare the constructor with non\sphinxhyphen{}scale dependent computations.

\end{fulllineitems}


\end{fulllineitems}

\index{constructor\_signed\_modularity (class in pygenstability.constructors)@\spxentry{constructor\_signed\_modularity}\spxextra{class in pygenstability.constructors}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{constructors:pygenstability.constructors.constructor_signed_modularity}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{  }}}\sphinxcode{\sphinxupquote{pygenstability.constructors.}}\sphinxbfcode{\sphinxupquote{constructor\_signed\_modularity}}}{\emph{\DUrole{n}{graph}}, \emph{\DUrole{n}{with\_spectral\_gap}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{exp\_comp\_mode}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}spectral\textquotesingle{}}}, \emph{\DUrole{o}{**}\DUrole{n}{kwargs}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Constructor of signed modularity.

\sphinxAtStartPar
This implementation is equation (18) of %
\begin{footnote}[1]\sphinxAtStartFootnote
Gómez, S., Jensen, P., \& Arenas, A. (2009). Analysis of community structure in
networks of correlated data. Physical Review E, 80(1), 016114.
%
\end{footnote}, where quality is the adjacency matrix and
the null model is the difference between the standard modularity null models based on
positive and negative degree vectors.
\subsubsection*{References}

\sphinxAtStartPar
The constructor calls the prepare method upon initialisation.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{graph}} (\sphinxstyleliteralemphasis{\sphinxupquote{csgraph}}) \textendash{} graph for which to run clustering

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{with\_spectral\_gap}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} set to True to use spectral gap to rescale

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kwargs}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} any other properties to pass to the constructor.

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{exp\_comp\_mode}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} mode to compute matrix exponential, can be expm or spectral

\end{itemize}

\end{description}\end{quote}
\index{prepare() (pygenstability.constructors.constructor\_signed\_modularity method)@\spxentry{prepare()}\spxextra{pygenstability.constructors.constructor\_signed\_modularity method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{constructors:pygenstability.constructors.constructor_signed_modularity.prepare}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{prepare}}}{\emph{\DUrole{o}{**}\DUrole{n}{kwargs}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Prepare the constructor with non\sphinxhyphen{}scale dependent computations.

\end{fulllineitems}


\end{fulllineitems}

\index{constructor\_signed\_combinatorial (class in pygenstability.constructors)@\spxentry{constructor\_signed\_combinatorial}\spxextra{class in pygenstability.constructors}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{constructors:pygenstability.constructors.constructor_signed_combinatorial}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{  }}}\sphinxcode{\sphinxupquote{pygenstability.constructors.}}\sphinxbfcode{\sphinxupquote{constructor\_signed\_combinatorial}}}{\emph{\DUrole{n}{graph}}, \emph{\DUrole{n}{with\_spectral\_gap}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{exp\_comp\_mode}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}spectral\textquotesingle{}}}, \emph{\DUrole{o}{**}\DUrole{n}{kwargs}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Constructor for continuous signed combinatorial Markov Stability.

\sphinxAtStartPar
The quality matrix is:
\begin{equation*}
\begin{split}F(t) = \exp(-Lt)^T\exp(-Lt)\end{split}
\end{equation*}
\sphinxAtStartPar
where \(L=D_{\mathrm{abs}}-A\) is the signed combinatorial Laplacian,
\(D_{\mathrm{abs}}=\mathrm{diag}(d_\mathrm{abs})\) the diagonal matrix of absolute node
strengths \(d_\mathrm{abs}\), and the associated null model  is given by
\(v_1=v_2=\boldsymbol{0}\), where \(\boldsymbol{0}\) is the vector of zeros.

\sphinxAtStartPar
The constructor calls the prepare method upon initialisation.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{graph}} (\sphinxstyleliteralemphasis{\sphinxupquote{csgraph}}) \textendash{} graph for which to run clustering

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{with\_spectral\_gap}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} set to True to use spectral gap to rescale

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kwargs}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} any other properties to pass to the constructor.

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{exp\_comp\_mode}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} mode to compute matrix exponential, can be expm or spectral

\end{itemize}

\end{description}\end{quote}
\index{prepare() (pygenstability.constructors.constructor\_signed\_combinatorial method)@\spxentry{prepare()}\spxextra{pygenstability.constructors.constructor\_signed\_combinatorial method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{constructors:pygenstability.constructors.constructor_signed_combinatorial.prepare}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{prepare}}}{\emph{\DUrole{o}{**}\DUrole{n}{kwargs}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Prepare the constructor with non\sphinxhyphen{}scale dependent computations.

\end{fulllineitems}

\index{get\_data() (pygenstability.constructors.constructor\_signed\_combinatorial method)@\spxentry{get\_data()}\spxextra{pygenstability.constructors.constructor\_signed\_combinatorial method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{constructors:pygenstability.constructors.constructor_signed_combinatorial.get_data}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_data}}}{\emph{\DUrole{n}{scale}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Return quality and null model at given scale.

\end{fulllineitems}


\end{fulllineitems}

\index{constructor\_directed (class in pygenstability.constructors)@\spxentry{constructor\_directed}\spxextra{class in pygenstability.constructors}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{constructors:pygenstability.constructors.constructor_directed}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{  }}}\sphinxcode{\sphinxupquote{pygenstability.constructors.}}\sphinxbfcode{\sphinxupquote{constructor\_directed}}}{\emph{\DUrole{n}{graph}}, \emph{\DUrole{n}{with\_spectral\_gap}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{exp\_comp\_mode}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}spectral\textquotesingle{}}}, \emph{\DUrole{o}{**}\DUrole{n}{kwargs}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Constructor for directed Markov stability.

\sphinxAtStartPar
The quality matrix is:
\begin{equation*}
\begin{split}F(t)=\Pi \exp\left(t \left(M(\alpha)-I\right)\right)\end{split}
\end{equation*}
\sphinxAtStartPar
where \(I\) denotes the identity matrix, \(M(\alpha)\) is the transition matrix of a
random walk with teleportation and damping factor \(0\le \alpha < 1\), and
\(\Pi=\mathrm{diag}(\pi)\) for the associated null model \(v_1=v_2=\pi\) given by the
eigenvector solving \(\pi M(\alpha) = \pi\), which is related to PageRank.

\sphinxAtStartPar
The transition matrix \(M(\alpha)\) is given by
\begin{equation*}
\begin{split}M(\alpha) = \alpha D^{-1}A+\left((1-\alpha)I+\alpha \mathrm{diag}(a)\right)
\frac{\boldsymbol{1}\boldsymbol{1}^T}{N},\end{split}
\end{equation*}
\sphinxAtStartPar
where \(D\) denotes the diagonal matrix of out\sphinxhyphen{}degrees with \(D_{ii}=1\) if the
out\sphinxhyphen{}degree \(d_i=0\) and \(a\) denotes the vector of dangling nodes, i.e. \(a_i=1\)
if the out\sphinxhyphen{}degree \(d_i=0\) and \(a_i=0\) otherwise.

\sphinxAtStartPar
The constructor calls the prepare method upon initialisation.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{graph}} (\sphinxstyleliteralemphasis{\sphinxupquote{csgraph}}) \textendash{} graph for which to run clustering

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{with\_spectral\_gap}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} set to True to use spectral gap to rescale

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kwargs}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} any other properties to pass to the constructor.

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{exp\_comp\_mode}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} mode to compute matrix exponential, can be expm or spectral

\end{itemize}

\end{description}\end{quote}
\index{prepare() (pygenstability.constructors.constructor\_directed method)@\spxentry{prepare()}\spxextra{pygenstability.constructors.constructor\_directed method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{constructors:pygenstability.constructors.constructor_directed.prepare}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{prepare}}}{\emph{\DUrole{o}{**}\DUrole{n}{kwargs}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Prepare the constructor with non\sphinxhyphen{}scale dependent computations.

\end{fulllineitems}


\end{fulllineitems}

\index{constructor\_linearized\_directed (class in pygenstability.constructors)@\spxentry{constructor\_linearized\_directed}\spxextra{class in pygenstability.constructors}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{constructors:pygenstability.constructors.constructor_linearized_directed}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{  }}}\sphinxcode{\sphinxupquote{pygenstability.constructors.}}\sphinxbfcode{\sphinxupquote{constructor\_linearized\_directed}}}{\emph{\DUrole{n}{graph}}, \emph{\DUrole{n}{with\_spectral\_gap}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{exp\_comp\_mode}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}spectral\textquotesingle{}}}, \emph{\DUrole{o}{**}\DUrole{n}{kwargs}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Constructor for linearized directed Markov stability.

\sphinxAtStartPar
The quality matrix is:
\begin{equation*}
\begin{split}F(t)=\Pi t M(\alpha)\end{split}
\end{equation*}
\sphinxAtStartPar
where \(M(\alpha)\) is the transition matrix of a random walk with teleportation and
damping factor \(0\le \alpha < 1\), and \(\Pi=\mathrm{diag}(\pi)\) for the associated
null model \(v_1=v_2=\pi\) given by the eigenvector solving \(\pi M(\alpha) = \pi\),
which is related to PageRank.

\sphinxAtStartPar
The transition matrix \(M(\alpha)\) is given by
\begin{equation*}
\begin{split}M(\alpha) = \alpha D^{-1}A+\left((1-\alpha)I+\alpha \mathrm{diag}(a)\right)
\frac{\boldsymbol{1}\boldsymbol{1}^T}{N},\end{split}
\end{equation*}
\sphinxAtStartPar
where \(I\) denotes the identity matrix, \(D\) denotes the diagonal matrix of
out\sphinxhyphen{}degrees with \(D_{ii}=1\) if the out\sphinxhyphen{}degree \(d_i=0\) and \(a\) denotes the
vector of dangling nodes, i.e. \(a_i=1\) if the out\sphinxhyphen{}degree \(d_i=0\) and \(a_i=0\)
otherwise.

\sphinxAtStartPar
The constructor calls the prepare method upon initialisation.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{graph}} (\sphinxstyleliteralemphasis{\sphinxupquote{csgraph}}) \textendash{} graph for which to run clustering

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{with\_spectral\_gap}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} set to True to use spectral gap to rescale

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kwargs}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} any other properties to pass to the constructor.

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{exp\_comp\_mode}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} mode to compute matrix exponential, can be expm or spectral

\end{itemize}

\end{description}\end{quote}
\index{prepare() (pygenstability.constructors.constructor\_linearized\_directed method)@\spxentry{prepare()}\spxextra{pygenstability.constructors.constructor\_linearized\_directed method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{constructors:pygenstability.constructors.constructor_linearized_directed.prepare}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{prepare}}}{\emph{\DUrole{o}{**}\DUrole{n}{kwargs}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Prepare the constructor with non\sphinxhyphen{}scale dependent computations.

\end{fulllineitems}


\end{fulllineitems}


\sphinxstepscope


\section{The pygenstability cli}
\label{\detokenize{app:module-pygenstability.app}}\label{\detokenize{app:the-pygenstability-cli}}\label{\detokenize{app::doc}}\index{module@\spxentry{module}!pygenstability.app@\spxentry{pygenstability.app}}\index{pygenstability.app@\spxentry{pygenstability.app}!module@\spxentry{module}}
\sphinxAtStartPar
Command line interface.


\subsection{cli}
\label{\detokenize{app:cli}}
\sphinxAtStartPar
App initialisation.

\begin{sphinxVerbatim}[commandchars=\\\{\}]
cli \PYG{o}{[}OPTIONS\PYG{o}{]} COMMAND \PYG{o}{[}ARGS\PYG{o}{]}...
\end{sphinxVerbatim}


\subsubsection{plot\_communities}
\label{\detokenize{app:cli-plot-communities}}
\sphinxAtStartPar
Plot communities on networkx graph.

\begin{sphinxVerbatim}[commandchars=\\\{\}]
cli plot\PYGZus{}communities \PYG{o}{[}OPTIONS\PYG{o}{]} GRAPH\PYGZus{}FILE RESULTS\PYGZus{}FILE
\end{sphinxVerbatim}
\subsubsection*{Arguments}
\index{cli\sphinxhyphen{}plot\_communities command line option@\spxentry{cli\sphinxhyphen{}plot\_communities command line option}!GRAPH\_FILE@\spxentry{GRAPH\_FILE}}\index{GRAPH\_FILE@\spxentry{GRAPH\_FILE}!cli\sphinxhyphen{}plot\_communities command line option@\spxentry{cli\sphinxhyphen{}plot\_communities command line option}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{app:cmdoption-cli-plot_communities-arg-GRAPH_FILE}}
\pysigstartsignatures
\pysigline{\sphinxbfcode{\sphinxupquote{GRAPH\_FILE}}\sphinxcode{\sphinxupquote{}}}
\pysigstopsignatures
\sphinxAtStartPar
Required argument

\end{fulllineitems}

\index{cli\sphinxhyphen{}plot\_communities command line option@\spxentry{cli\sphinxhyphen{}plot\_communities command line option}!RESULTS\_FILE@\spxentry{RESULTS\_FILE}}\index{RESULTS\_FILE@\spxentry{RESULTS\_FILE}!cli\sphinxhyphen{}plot\_communities command line option@\spxentry{cli\sphinxhyphen{}plot\_communities command line option}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{app:cmdoption-cli-plot_communities-arg-RESULTS_FILE}}
\pysigstartsignatures
\pysigline{\sphinxbfcode{\sphinxupquote{RESULTS\_FILE}}\sphinxcode{\sphinxupquote{}}}
\pysigstopsignatures
\sphinxAtStartPar
Required argument

\end{fulllineitems}



\subsubsection{plot\_scan}
\label{\detokenize{app:cli-plot-scan}}
\sphinxAtStartPar
Plot results in scan plot.

\begin{sphinxVerbatim}[commandchars=\\\{\}]
cli plot\PYGZus{}scan \PYG{o}{[}OPTIONS\PYG{o}{]} RESULTS\PYGZus{}FILE
\end{sphinxVerbatim}
\subsubsection*{Arguments}
\index{cli\sphinxhyphen{}plot\_scan command line option@\spxentry{cli\sphinxhyphen{}plot\_scan command line option}!RESULTS\_FILE@\spxentry{RESULTS\_FILE}}\index{RESULTS\_FILE@\spxentry{RESULTS\_FILE}!cli\sphinxhyphen{}plot\_scan command line option@\spxentry{cli\sphinxhyphen{}plot\_scan command line option}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{app:cmdoption-cli-plot_scan-arg-RESULTS_FILE}}
\pysigstartsignatures
\pysigline{\sphinxbfcode{\sphinxupquote{RESULTS\_FILE}}\sphinxcode{\sphinxupquote{}}}
\pysigstopsignatures
\sphinxAtStartPar
Required argument

\end{fulllineitems}



\subsubsection{run}
\label{\detokenize{app:cli-run}}
\sphinxAtStartPar
Run pygenstability.

\sphinxAtStartPar
graph\_file: path to either a .pkl with adjacency matrix in sparse format,
or a text file with three columns encoding node indices and edge weight.
The columns need a header, or the first line will be dropped.
Notice that doubled edges with opposite orientations are needed for symetric graph.

\sphinxAtStartPar
See \sphinxurl{https://barahona-research-group.github.io/PyGenStability/} for more information.

\begin{sphinxVerbatim}[commandchars=\\\{\}]
cli run \PYG{o}{[}OPTIONS\PYG{o}{]} GRAPH\PYGZus{}FILE
\end{sphinxVerbatim}
\subsubsection*{Options}
\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!\sphinxhyphen{}\sphinxhyphen{}constructor@\spxentry{\sphinxhyphen{}\sphinxhyphen{}constructor}}\index{\sphinxhyphen{}\sphinxhyphen{}constructor@\spxentry{\sphinxhyphen{}\sphinxhyphen{}constructor}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{app:cmdoption-cli-run-constructor}}
\pysigstartsignatures
\pysigline{\sphinxbfcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}constructor}}\sphinxcode{\sphinxupquote{~\textless{}constructor\textgreater{}}}}
\pysigstopsignatures
\sphinxAtStartPar
Name of the quality constructor.
\begin{quote}\begin{description}
\sphinxlineitem{Default}
\sphinxAtStartPar
linearized

\end{description}\end{quote}

\end{fulllineitems}

\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!\sphinxhyphen{}\sphinxhyphen{}min\sphinxhyphen{}scale@\spxentry{\sphinxhyphen{}\sphinxhyphen{}min\sphinxhyphen{}scale}}\index{\sphinxhyphen{}\sphinxhyphen{}min\sphinxhyphen{}scale@\spxentry{\sphinxhyphen{}\sphinxhyphen{}min\sphinxhyphen{}scale}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{app:cmdoption-cli-run-min-scale}}
\pysigstartsignatures
\pysigline{\sphinxbfcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}min\sphinxhyphen{}scale}}\sphinxcode{\sphinxupquote{~\textless{}min\_scale\textgreater{}}}}
\pysigstopsignatures
\sphinxAtStartPar
Minimum scale.
\begin{quote}\begin{description}
\sphinxlineitem{Default}
\sphinxAtStartPar
\sphinxhyphen{}2.0

\end{description}\end{quote}

\end{fulllineitems}

\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!\sphinxhyphen{}\sphinxhyphen{}max\sphinxhyphen{}scale@\spxentry{\sphinxhyphen{}\sphinxhyphen{}max\sphinxhyphen{}scale}}\index{\sphinxhyphen{}\sphinxhyphen{}max\sphinxhyphen{}scale@\spxentry{\sphinxhyphen{}\sphinxhyphen{}max\sphinxhyphen{}scale}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{app:cmdoption-cli-run-max-scale}}
\pysigstartsignatures
\pysigline{\sphinxbfcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}max\sphinxhyphen{}scale}}\sphinxcode{\sphinxupquote{~\textless{}max\_scale\textgreater{}}}}
\pysigstopsignatures
\sphinxAtStartPar
Maximum scale.
\begin{quote}\begin{description}
\sphinxlineitem{Default}
\sphinxAtStartPar
0.5

\end{description}\end{quote}

\end{fulllineitems}

\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!\sphinxhyphen{}\sphinxhyphen{}n\sphinxhyphen{}scale@\spxentry{\sphinxhyphen{}\sphinxhyphen{}n\sphinxhyphen{}scale}}\index{\sphinxhyphen{}\sphinxhyphen{}n\sphinxhyphen{}scale@\spxentry{\sphinxhyphen{}\sphinxhyphen{}n\sphinxhyphen{}scale}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{app:cmdoption-cli-run-n-scale}}
\pysigstartsignatures
\pysigline{\sphinxbfcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}n\sphinxhyphen{}scale}}\sphinxcode{\sphinxupquote{~\textless{}n\_scale\textgreater{}}}}
\pysigstopsignatures
\sphinxAtStartPar
Number of scale steps.
\begin{quote}\begin{description}
\sphinxlineitem{Default}
\sphinxAtStartPar
20

\end{description}\end{quote}

\end{fulllineitems}

\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!\sphinxhyphen{}\sphinxhyphen{}log\sphinxhyphen{}scale@\spxentry{\sphinxhyphen{}\sphinxhyphen{}log\sphinxhyphen{}scale}}\index{\sphinxhyphen{}\sphinxhyphen{}log\sphinxhyphen{}scale@\spxentry{\sphinxhyphen{}\sphinxhyphen{}log\sphinxhyphen{}scale}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{app:cmdoption-cli-run-log-scale}}
\pysigstartsignatures
\pysigline{\sphinxbfcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}log\sphinxhyphen{}scale}}\sphinxcode{\sphinxupquote{~\textless{}log\_scale\textgreater{}}}}
\pysigstopsignatures
\sphinxAtStartPar
Use linear or log scales.
\begin{quote}\begin{description}
\sphinxlineitem{Default}
\sphinxAtStartPar
True

\end{description}\end{quote}

\end{fulllineitems}

\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!\sphinxhyphen{}\sphinxhyphen{}n\sphinxhyphen{}tries@\spxentry{\sphinxhyphen{}\sphinxhyphen{}n\sphinxhyphen{}tries}}\index{\sphinxhyphen{}\sphinxhyphen{}n\sphinxhyphen{}tries@\spxentry{\sphinxhyphen{}\sphinxhyphen{}n\sphinxhyphen{}tries}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{app:cmdoption-cli-run-n-tries}}
\pysigstartsignatures
\pysigline{\sphinxbfcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}n\sphinxhyphen{}tries}}\sphinxcode{\sphinxupquote{~\textless{}n\_tries\textgreater{}}}}
\pysigstopsignatures
\sphinxAtStartPar
Number of Louvain evaluations.
\begin{quote}\begin{description}
\sphinxlineitem{Default}
\sphinxAtStartPar
100

\end{description}\end{quote}

\end{fulllineitems}

\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!\sphinxhyphen{}\sphinxhyphen{}NVI@\spxentry{\sphinxhyphen{}\sphinxhyphen{}NVI}}\index{\sphinxhyphen{}\sphinxhyphen{}NVI@\spxentry{\sphinxhyphen{}\sphinxhyphen{}NVI}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}NVI@\spxentry{\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}NVI}}\index{\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}NVI@\spxentry{\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}NVI}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{app:cmdoption-cli-run-NVI}}
\pysigstartsignatures
\pysigline{\sphinxbfcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}NVI}}\sphinxcode{\sphinxupquote{}}\sphinxcode{\sphinxupquote{,~}}\sphinxbfcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}NVI}}\sphinxcode{\sphinxupquote{}}}
\pysigstopsignatures
\sphinxAtStartPar
Compute the normalized variation of information between runs.
\begin{quote}\begin{description}
\sphinxlineitem{Default}
\sphinxAtStartPar
True

\end{description}\end{quote}

\end{fulllineitems}

\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!\sphinxhyphen{}\sphinxhyphen{}n\sphinxhyphen{}NVI@\spxentry{\sphinxhyphen{}\sphinxhyphen{}n\sphinxhyphen{}NVI}}\index{\sphinxhyphen{}\sphinxhyphen{}n\sphinxhyphen{}NVI@\spxentry{\sphinxhyphen{}\sphinxhyphen{}n\sphinxhyphen{}NVI}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{app:cmdoption-cli-run-n-NVI}}
\pysigstartsignatures
\pysigline{\sphinxbfcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}n\sphinxhyphen{}NVI}}\sphinxcode{\sphinxupquote{~\textless{}n\_nvi\textgreater{}}}}
\pysigstopsignatures
\sphinxAtStartPar
Number of randomly chosen runs to estimate the NVI.
\begin{quote}\begin{description}
\sphinxlineitem{Default}
\sphinxAtStartPar
20

\end{description}\end{quote}

\end{fulllineitems}

\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!\sphinxhyphen{}\sphinxhyphen{}postprocessing@\spxentry{\sphinxhyphen{}\sphinxhyphen{}postprocessing}}\index{\sphinxhyphen{}\sphinxhyphen{}postprocessing@\spxentry{\sphinxhyphen{}\sphinxhyphen{}postprocessing}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}postprocessing@\spxentry{\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}postprocessing}}\index{\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}postprocessing@\spxentry{\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}postprocessing}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{app:cmdoption-cli-run-postprocessing}}
\pysigstartsignatures
\pysigline{\sphinxbfcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}postprocessing}}\sphinxcode{\sphinxupquote{}}\sphinxcode{\sphinxupquote{,~}}\sphinxbfcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}postprocessing}}\sphinxcode{\sphinxupquote{}}}
\pysigstopsignatures
\sphinxAtStartPar
Apply the final postprocessing step.
\begin{quote}\begin{description}
\sphinxlineitem{Default}
\sphinxAtStartPar
True

\end{description}\end{quote}

\end{fulllineitems}

\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!\sphinxhyphen{}\sphinxhyphen{}ttprime@\spxentry{\sphinxhyphen{}\sphinxhyphen{}ttprime}}\index{\sphinxhyphen{}\sphinxhyphen{}ttprime@\spxentry{\sphinxhyphen{}\sphinxhyphen{}ttprime}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}ttprime@\spxentry{\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}ttprime}}\index{\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}ttprime@\spxentry{\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}ttprime}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{app:cmdoption-cli-run-ttprime}}
\pysigstartsignatures
\pysigline{\sphinxbfcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}ttprime}}\sphinxcode{\sphinxupquote{}}\sphinxcode{\sphinxupquote{,~}}\sphinxbfcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}ttprime}}\sphinxcode{\sphinxupquote{}}}
\pysigstopsignatures
\sphinxAtStartPar
Compute the ttprime matrix.
\begin{quote}\begin{description}
\sphinxlineitem{Default}
\sphinxAtStartPar
True

\end{description}\end{quote}

\end{fulllineitems}

\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!\sphinxhyphen{}\sphinxhyphen{}spectral\sphinxhyphen{}gap@\spxentry{\sphinxhyphen{}\sphinxhyphen{}spectral\sphinxhyphen{}gap}}\index{\sphinxhyphen{}\sphinxhyphen{}spectral\sphinxhyphen{}gap@\spxentry{\sphinxhyphen{}\sphinxhyphen{}spectral\sphinxhyphen{}gap}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}spectral\sphinxhyphen{}gap@\spxentry{\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}spectral\sphinxhyphen{}gap}}\index{\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}spectral\sphinxhyphen{}gap@\spxentry{\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}spectral\sphinxhyphen{}gap}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{app:cmdoption-cli-run-spectral-gap}}
\pysigstartsignatures
\pysigline{\sphinxbfcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}spectral\sphinxhyphen{}gap}}\sphinxcode{\sphinxupquote{}}\sphinxcode{\sphinxupquote{,~}}\sphinxbfcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}spectral\sphinxhyphen{}gap}}\sphinxcode{\sphinxupquote{}}}
\pysigstopsignatures
\sphinxAtStartPar
Normalize scale by spectral gap.
\begin{quote}\begin{description}
\sphinxlineitem{Default}
\sphinxAtStartPar
True

\end{description}\end{quote}

\end{fulllineitems}

\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!\sphinxhyphen{}\sphinxhyphen{}result\sphinxhyphen{}file@\spxentry{\sphinxhyphen{}\sphinxhyphen{}result\sphinxhyphen{}file}}\index{\sphinxhyphen{}\sphinxhyphen{}result\sphinxhyphen{}file@\spxentry{\sphinxhyphen{}\sphinxhyphen{}result\sphinxhyphen{}file}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{app:cmdoption-cli-run-result-file}}
\pysigstartsignatures
\pysigline{\sphinxbfcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}result\sphinxhyphen{}file}}\sphinxcode{\sphinxupquote{~\textless{}result\_file\textgreater{}}}}
\pysigstopsignatures
\sphinxAtStartPar
Path to the result file.
\begin{quote}\begin{description}
\sphinxlineitem{Default}
\sphinxAtStartPar
results.pkl

\end{description}\end{quote}

\end{fulllineitems}

\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!\sphinxhyphen{}\sphinxhyphen{}n\sphinxhyphen{}workers@\spxentry{\sphinxhyphen{}\sphinxhyphen{}n\sphinxhyphen{}workers}}\index{\sphinxhyphen{}\sphinxhyphen{}n\sphinxhyphen{}workers@\spxentry{\sphinxhyphen{}\sphinxhyphen{}n\sphinxhyphen{}workers}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{app:cmdoption-cli-run-n-workers}}
\pysigstartsignatures
\pysigline{\sphinxbfcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}n\sphinxhyphen{}workers}}\sphinxcode{\sphinxupquote{~\textless{}n\_workers\textgreater{}}}}
\pysigstopsignatures
\sphinxAtStartPar
Number of workers for multiprocessing.
\begin{quote}\begin{description}
\sphinxlineitem{Default}
\sphinxAtStartPar
4

\end{description}\end{quote}

\end{fulllineitems}

\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!\sphinxhyphen{}\sphinxhyphen{}tqdm\sphinxhyphen{}disable@\spxentry{\sphinxhyphen{}\sphinxhyphen{}tqdm\sphinxhyphen{}disable}}\index{\sphinxhyphen{}\sphinxhyphen{}tqdm\sphinxhyphen{}disable@\spxentry{\sphinxhyphen{}\sphinxhyphen{}tqdm\sphinxhyphen{}disable}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{app:cmdoption-cli-run-tqdm-disable}}
\pysigstartsignatures
\pysigline{\sphinxbfcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}tqdm\sphinxhyphen{}disable}}\sphinxcode{\sphinxupquote{~\textless{}tqdm\_disable\textgreater{}}}}
\pysigstopsignatures
\sphinxAtStartPar
disable progress bars
\begin{quote}\begin{description}
\sphinxlineitem{Default}
\sphinxAtStartPar
False

\end{description}\end{quote}

\end{fulllineitems}

\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!\sphinxhyphen{}\sphinxhyphen{}method@\spxentry{\sphinxhyphen{}\sphinxhyphen{}method}}\index{\sphinxhyphen{}\sphinxhyphen{}method@\spxentry{\sphinxhyphen{}\sphinxhyphen{}method}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{app:cmdoption-cli-run-method}}
\pysigstartsignatures
\pysigline{\sphinxbfcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}method}}\sphinxcode{\sphinxupquote{~\textless{}method\textgreater{}}}}
\pysigstopsignatures
\sphinxAtStartPar
Method to solve modularity, either Louvain or Leiden
\begin{quote}\begin{description}
\sphinxlineitem{Default}
\sphinxAtStartPar
louvain

\end{description}\end{quote}

\end{fulllineitems}

\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!\sphinxhyphen{}\sphinxhyphen{}with\sphinxhyphen{}optimal\sphinxhyphen{}scales@\spxentry{\sphinxhyphen{}\sphinxhyphen{}with\sphinxhyphen{}optimal\sphinxhyphen{}scales}}\index{\sphinxhyphen{}\sphinxhyphen{}with\sphinxhyphen{}optimal\sphinxhyphen{}scales@\spxentry{\sphinxhyphen{}\sphinxhyphen{}with\sphinxhyphen{}optimal\sphinxhyphen{}scales}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}with\sphinxhyphen{}optimal\sphinxhyphen{}scales@\spxentry{\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}with\sphinxhyphen{}optimal\sphinxhyphen{}scales}}\index{\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}with\sphinxhyphen{}optimal\sphinxhyphen{}scales@\spxentry{\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}with\sphinxhyphen{}optimal\sphinxhyphen{}scales}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{app:cmdoption-cli-run-with-optimal-scales}}
\pysigstartsignatures
\pysigline{\sphinxbfcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}with\sphinxhyphen{}optimal\sphinxhyphen{}scales}}\sphinxcode{\sphinxupquote{}}\sphinxcode{\sphinxupquote{,~}}\sphinxbfcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}no\sphinxhyphen{}with\sphinxhyphen{}optimal\sphinxhyphen{}scales}}\sphinxcode{\sphinxupquote{}}}
\pysigstopsignatures
\sphinxAtStartPar
Search for optimal scales
\begin{quote}\begin{description}
\sphinxlineitem{Default}
\sphinxAtStartPar
True

\end{description}\end{quote}

\end{fulllineitems}

\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!\sphinxhyphen{}\sphinxhyphen{}exp\sphinxhyphen{}comp\sphinxhyphen{}mode@\spxentry{\sphinxhyphen{}\sphinxhyphen{}exp\sphinxhyphen{}comp\sphinxhyphen{}mode}}\index{\sphinxhyphen{}\sphinxhyphen{}exp\sphinxhyphen{}comp\sphinxhyphen{}mode@\spxentry{\sphinxhyphen{}\sphinxhyphen{}exp\sphinxhyphen{}comp\sphinxhyphen{}mode}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{app:cmdoption-cli-run-exp-comp-mode}}
\pysigstartsignatures
\pysigline{\sphinxbfcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}exp\sphinxhyphen{}comp\sphinxhyphen{}mode}}\sphinxcode{\sphinxupquote{~\textless{}exp\_comp\_mode\textgreater{}}}}
\pysigstopsignatures
\sphinxAtStartPar
Method to compute matrix exponential, can be ‘spectral’ or ‘expm’
\begin{quote}\begin{description}
\sphinxlineitem{Default}
\sphinxAtStartPar
spectral

\end{description}\end{quote}

\end{fulllineitems}

\subsubsection*{Arguments}
\index{cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}!GRAPH\_FILE@\spxentry{GRAPH\_FILE}}\index{GRAPH\_FILE@\spxentry{GRAPH\_FILE}!cli\sphinxhyphen{}run command line option@\spxentry{cli\sphinxhyphen{}run command line option}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{app:cmdoption-cli-run-arg-GRAPH_FILE}}
\pysigstartsignatures
\pysigline{\sphinxbfcode{\sphinxupquote{GRAPH\_FILE}}\sphinxcode{\sphinxupquote{}}}
\pysigstopsignatures
\sphinxAtStartPar
Required argument

\end{fulllineitems}


\sphinxstepscope


\section{Plotting module}
\label{\detokenize{plotting:module-pygenstability.plotting}}\label{\detokenize{plotting:plotting-module}}\label{\detokenize{plotting::doc}}\index{module@\spxentry{module}!pygenstability.plotting@\spxentry{pygenstability.plotting}}\index{pygenstability.plotting@\spxentry{pygenstability.plotting}!module@\spxentry{module}}
\sphinxAtStartPar
Plotting functions.
\index{plot\_scan() (in module pygenstability.plotting)@\spxentry{plot\_scan()}\spxextra{in module pygenstability.plotting}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{plotting:pygenstability.plotting.plot_scan}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{pygenstability.plotting.}}\sphinxbfcode{\sphinxupquote{plot\_scan}}}{\emph{\DUrole{n}{all\_results}}, \emph{\DUrole{n}{scale\_axis}\DUrole{o}{=}\DUrole{default_value}{True}}, \emph{\DUrole{n}{figure\_name}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}scan\_results.pdf\textquotesingle{}}}, \emph{\DUrole{n}{use\_plotly}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{live}\DUrole{o}{=}\DUrole{default_value}{True}}, \emph{\DUrole{n}{plotly\_filename}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}scan\_results.html\textquotesingle{}}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plot results of pygenstability with matplotlib or plotly.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{all\_results}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} results of pygenstability scan

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{scale\_axis}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} display scale of scale index on scale axis

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figure\_name}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} name of matplotlib figure

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{use\_plotly}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} use matplotlib or plotly backend

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{live}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} for plotly backend, open browser with pot

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{plotly\_filename}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} filename of .html figure from plotly

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_scan\_plotly() (in module pygenstability.plotting)@\spxentry{plot\_scan\_plotly()}\spxextra{in module pygenstability.plotting}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{plotting:pygenstability.plotting.plot_scan_plotly}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{pygenstability.plotting.}}\sphinxbfcode{\sphinxupquote{plot\_scan\_plotly}}}{\emph{\DUrole{n}{all\_results}}, \emph{\DUrole{n}{live}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{filename}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}clusters.html\textquotesingle{}}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plot results of pygenstability with plotly.

\end{fulllineitems}

\index{plot\_single\_partition() (in module pygenstability.plotting)@\spxentry{plot\_single\_partition()}\spxextra{in module pygenstability.plotting}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{plotting:pygenstability.plotting.plot_single_partition}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{pygenstability.plotting.}}\sphinxbfcode{\sphinxupquote{plot\_single\_partition}}}{\emph{\DUrole{n}{graph}}, \emph{\DUrole{n}{all\_results}}, \emph{\DUrole{n}{scale\_id}}, \emph{\DUrole{n}{edge\_color}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}0.5\textquotesingle{}}}, \emph{\DUrole{n}{edge\_width}\DUrole{o}{=}\DUrole{default_value}{0.5}}, \emph{\DUrole{n}{node\_size}\DUrole{o}{=}\DUrole{default_value}{100}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plot the community structures for a given scale.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{graph}} (\sphinxstyleliteralemphasis{\sphinxupquote{networkx.Graph}}) \textendash{} graph to plot

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{all\_results}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} results of pygenstability scan

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{scale\_id}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} index of scale to plot

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{folder}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} folder to save figures

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{edge\_color}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} color of edges

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{edge\_width}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} width of edges

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{node\_size}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} size of nodes

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ext}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} extension of figures files

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_optimal\_partitions() (in module pygenstability.plotting)@\spxentry{plot\_optimal\_partitions()}\spxextra{in module pygenstability.plotting}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{plotting:pygenstability.plotting.plot_optimal_partitions}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{pygenstability.plotting.}}\sphinxbfcode{\sphinxupquote{plot\_optimal\_partitions}}}{\emph{\DUrole{n}{graph}}, \emph{\DUrole{n}{all\_results}}, \emph{\DUrole{n}{edge\_color}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}0.5\textquotesingle{}}}, \emph{\DUrole{n}{edge\_width}\DUrole{o}{=}\DUrole{default_value}{0.5}}, \emph{\DUrole{n}{folder}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}optimal\_partitions\textquotesingle{}}}, \emph{\DUrole{n}{ext}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}.pdf\textquotesingle{}}}, \emph{\DUrole{n}{show}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plot the community structures at each optimal scale.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{graph}} (\sphinxstyleliteralemphasis{\sphinxupquote{networkx.Graph}}) \textendash{} graph to plot

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{all\_results}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} results of pygenstability scan

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{edge\_color}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} color of edges

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{edge\_width}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} width of edgs

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{folder}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} folder to save figures

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ext}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} extension of figures files

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{show}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} show each plot with plt.show() or not

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_communities() (in module pygenstability.plotting)@\spxentry{plot\_communities()}\spxextra{in module pygenstability.plotting}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{plotting:pygenstability.plotting.plot_communities}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{pygenstability.plotting.}}\sphinxbfcode{\sphinxupquote{plot\_communities}}}{\emph{\DUrole{n}{graph}}, \emph{\DUrole{n}{all\_results}}, \emph{\DUrole{n}{folder}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}communities\textquotesingle{}}}, \emph{\DUrole{n}{edge\_color}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}0.5\textquotesingle{}}}, \emph{\DUrole{n}{edge\_width}\DUrole{o}{=}\DUrole{default_value}{0.5}}, \emph{\DUrole{n}{ext}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}.pdf\textquotesingle{}}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plot the community structures at each scale in a folder.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{graph}} (\sphinxstyleliteralemphasis{\sphinxupquote{networkx.Graph}}) \textendash{} graph to plot

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{all\_results}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} results of pygenstability scan

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{folder}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} folder to save figures

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{edge\_color}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} color of edges

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{edge\_width}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} width of edgs

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ext}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} extension of figures files

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_communities\_matrix() (in module pygenstability.plotting)@\spxentry{plot\_communities\_matrix()}\spxextra{in module pygenstability.plotting}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{plotting:pygenstability.plotting.plot_communities_matrix}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{pygenstability.plotting.}}\sphinxbfcode{\sphinxupquote{plot\_communities\_matrix}}}{\emph{\DUrole{n}{graph}}, \emph{\DUrole{n}{all\_results}}, \emph{\DUrole{n}{folder}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}communities\_matrix\textquotesingle{}}}, \emph{\DUrole{n}{ext}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}.pdf\textquotesingle{}}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plot communities at all scales in matrix form.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{graph}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} as a numpy matrix

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{all\_results}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} clustring results

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{folder}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} folder to save figures

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ext}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} figure file format

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_scan\_plt() (in module pygenstability.plotting)@\spxentry{plot\_scan\_plt()}\spxextra{in module pygenstability.plotting}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{plotting:pygenstability.plotting.plot_scan_plt}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{pygenstability.plotting.}}\sphinxbfcode{\sphinxupquote{plot\_scan\_plt}}}{\emph{\DUrole{n}{all\_results}}, \emph{\DUrole{n}{scale\_axis}\DUrole{o}{=}\DUrole{default_value}{True}}, \emph{\DUrole{n}{figure\_name}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}scan\_results.svg\textquotesingle{}}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plot results of pygenstability with matplotlib.

\end{fulllineitems}

\index{plot\_clustered\_adjacency() (in module pygenstability.plotting)@\spxentry{plot\_clustered\_adjacency()}\spxextra{in module pygenstability.plotting}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{plotting:pygenstability.plotting.plot_clustered_adjacency}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{pygenstability.plotting.}}\sphinxbfcode{\sphinxupquote{plot\_clustered\_adjacency}}}{\emph{\DUrole{n}{adjacency}}, \emph{\DUrole{n}{all\_results}}, \emph{\DUrole{n}{scale}}, \emph{\DUrole{n}{labels}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(12, 10)}}, \emph{\DUrole{n}{cmap}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}Blues\textquotesingle{}}}, \emph{\DUrole{n}{figure\_name}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}clustered\_adjacency.pdf\textquotesingle{}}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plot the clustered adjacency matrix of the graph at a given scale.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{adjacency}} (\sphinxstyleliteralemphasis{\sphinxupquote{ndarray}}) \textendash{} adjacency matrix to plot

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{all\_results}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} results of PyGenStability

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{scale}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} scale index for clustering

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{labels}} (\sphinxstyleliteralemphasis{\sphinxupquote{list}}) \textendash{} node labels, or None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tubple}}) \textendash{} figure size

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{cmap}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} colormap for matrix elements

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figure\_name}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} filename of the figure with extension

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}


\sphinxstepscope


\section{Optimal scales module}
\label{\detokenize{optimal_scales:module-pygenstability.optimal_scales}}\label{\detokenize{optimal_scales:optimal-scales-module}}\label{\detokenize{optimal_scales::doc}}\index{module@\spxentry{module}!pygenstability.optimal\_scales@\spxentry{pygenstability.optimal\_scales}}\index{pygenstability.optimal\_scales@\spxentry{pygenstability.optimal\_scales}!module@\spxentry{module}}
\sphinxAtStartPar
Detect optimal scales from a scale scan.
\index{identify\_optimal\_scales() (in module pygenstability.optimal\_scales)@\spxentry{identify\_optimal\_scales()}\spxextra{in module pygenstability.optimal\_scales}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{optimal_scales:pygenstability.optimal_scales.identify_optimal_scales}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{pygenstability.optimal\_scales.}}\sphinxbfcode{\sphinxupquote{identify\_optimal\_scales}}}{\emph{\DUrole{n}{results}}, \emph{\DUrole{n}{kernel\_size}\DUrole{o}{=}\DUrole{default_value}{3}}, \emph{\DUrole{n}{window\_size}\DUrole{o}{=}\DUrole{default_value}{3}}, \emph{\DUrole{n}{max\_nvi}\DUrole{o}{=}\DUrole{default_value}{1}}, \emph{\DUrole{n}{basin\_radius}\DUrole{o}{=}\DUrole{default_value}{1}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Identifies optimal scales in Markov Stability %
\begin{footnote}[1]\sphinxAtStartFootnote
D. J. Schindler, J. Clarke, and M. Barahona, ‘Multiscale Mobility Patterns and
the Restriction of Human Movement’, \sphinxstyleemphasis{arXiv:2201.06323}, 2023
%
\end{footnote}.

\sphinxAtStartPar
Robust scales are found in a sequential way. We first search for large diagonal blocks
of low values in the NVI(t, t’) matrix that are located at local minima of its pooled
diagonal, called block detection curve, and we obtain basins of fixed radius around
these local minima. We then determine the minima of the NVI(t) curve for each basin,
and these minima correspond to the robust partitions of the network.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{results}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} the results from a Markov Stability calculation

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kernel\_size}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} size of kernel for average\sphinxhyphen{}pooling of the NVI(t,t’) matrix

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{window\_size}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} size of window for moving mean, to smooth the pooled diagonal

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{max\_nvi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} threshold for local minima of the pooled diagonal

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{basin\_radius}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} radius of basin around local minima of the pooled diagonal

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
‘selected\_partitions’ and ‘block\_detection\_curve’

\sphinxlineitem{Return type}
\sphinxAtStartPar
result dictionary with two new keys

\end{description}\end{quote}
\subsubsection*{References}

\end{fulllineitems}


\sphinxstepscope


\section{I/O module}
\label{\detokenize{io:module-pygenstability.io}}\label{\detokenize{io:i-o-module}}\label{\detokenize{io::doc}}\index{module@\spxentry{module}!pygenstability.io@\spxentry{pygenstability.io}}\index{pygenstability.io@\spxentry{pygenstability.io}!module@\spxentry{module}}
\sphinxAtStartPar
I/O functions.
\index{save\_results() (in module pygenstability.io)@\spxentry{save\_results()}\spxextra{in module pygenstability.io}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{io:pygenstability.io.save_results}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{pygenstability.io.}}\sphinxbfcode{\sphinxupquote{save\_results}}}{\emph{\DUrole{n}{all\_results}}, \emph{\DUrole{n}{filename}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}results.pkl\textquotesingle{}}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Save results in a pickle.

\end{fulllineitems}

\index{load\_results() (in module pygenstability.io)@\spxentry{load\_results()}\spxextra{in module pygenstability.io}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{io:pygenstability.io.load_results}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{pygenstability.io.}}\sphinxbfcode{\sphinxupquote{load\_results}}}{\emph{\DUrole{n}{filename}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}results.pkl\textquotesingle{}}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Load results from a pickle.

\end{fulllineitems}


\sphinxstepscope


\section{Example: Markov Stability with PyGenStability}
\label{\detokenize{examples/example:Example:-Markov-Stability-with-PyGenStability}}\label{\detokenize{examples/example::doc}}
\sphinxAtStartPar
This example illustrates how to use PyGenStability for multiscale community detection with Markov Stability analysis.

\begin{sphinxuseclass}{nbinput}
\begin{sphinxuseclass}{nblast}
{
\sphinxsetup{VerbatimColor={named}{nbsphinx-code-bg}}
\sphinxsetup{VerbatimBorderColor={named}{nbsphinx-code-border}}
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\llap{\color{nbsphinxin}[1]:\,\hspace{\fboxrule}\hspace{\fboxsep}}\PYG{k+kn}{import} \PYG{n+nn}{matplotlib}\PYG{n+nn}{.}\PYG{n+nn}{pyplot} \PYG{k}{as} \PYG{n+nn}{plt}
\PYG{k+kn}{import} \PYG{n+nn}{networkx} \PYG{k}{as} \PYG{n+nn}{nx}
\PYG{k+kn}{import} \PYG{n+nn}{scipy}\PYG{n+nn}{.}\PYG{n+nn}{sparse} \PYG{k}{as} \PYG{n+nn}{sp}

\PYG{k+kn}{import} \PYG{n+nn}{pygenstability} \PYG{k}{as} \PYG{n+nn}{pgs}
\PYG{k+kn}{from} \PYG{n+nn}{pygenstability} \PYG{k+kn}{import} \PYG{n}{plotting}
\PYG{k+kn}{from} \PYG{n+nn}{pygenstability}\PYG{n+nn}{.}\PYG{n+nn}{pygenstability} \PYG{k+kn}{import} \PYG{n}{evaluate\PYGZus{}NVI}

\PYG{k+kn}{from} \PYG{n+nn}{multiscale\PYGZus{}example} \PYG{k+kn}{import} \PYG{n}{create\PYGZus{}graph}
\end{sphinxVerbatim}
}

\end{sphinxuseclass}
\end{sphinxuseclass}
\sphinxAtStartPar
We first create a stochastic block model graph with some planted partitions at different scales.

\begin{sphinxuseclass}{nbinput}
{
\sphinxsetup{VerbatimColor={named}{nbsphinx-code-bg}}
\sphinxsetup{VerbatimBorderColor={named}{nbsphinx-code-border}}
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\llap{\color{nbsphinxin}[2]:\,\hspace{\fboxrule}\hspace{\fboxsep}}\PYG{n}{A}\PYG{p}{,} \PYG{n}{coarse\PYGZus{}scale\PYGZus{}id}\PYG{p}{,} \PYG{n}{middle\PYGZus{}scale\PYGZus{}id}\PYG{p}{,} \PYG{n}{fine\PYGZus{}scale\PYGZus{}id} \PYG{o}{=} \PYG{n}{create\PYGZus{}graph}\PYG{p}{(}\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} Create nx graph}
\PYG{n}{G} \PYG{o}{=} \PYG{n}{nx}\PYG{o}{.}\PYG{n}{from\PYGZus{}numpy\PYGZus{}array}\PYG{p}{(}\PYG{n}{A}\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} Compute spring layout}
\PYG{n}{pos\PYGZus{}G} \PYG{o}{=} \PYG{n}{nx}\PYG{o}{.}\PYG{n}{layout}\PYG{o}{.}\PYG{n}{spring\PYGZus{}layout}\PYG{p}{(}\PYG{n}{G}\PYG{p}{,} \PYG{n}{seed}\PYG{o}{=}\PYG{l+m+mi}{1}\PYG{p}{)}


\PYG{c+c1}{\PYGZsh{} plot matrix}
\PYG{n}{plt}\PYG{o}{.}\PYG{n}{figure}\PYG{p}{(}\PYG{p}{)}
\PYG{n}{plt}\PYG{o}{.}\PYG{n}{imshow}\PYG{p}{(}\PYG{n}{A}\PYG{p}{,} \PYG{n}{interpolation}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{nearest}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{)}

\end{sphinxVerbatim}
}

\end{sphinxuseclass}
\begin{sphinxuseclass}{nboutput}
{

\kern-\sphinxverbatimsmallskipamount\kern-\baselineskip
\kern+\FrameHeightAdjust\kern-\fboxrule
\vspace{\nbsphinxcodecellspacing}

\sphinxsetup{VerbatimColor={named}{white}}
\sphinxsetup{VerbatimBorderColor={named}{nbsphinx-code-border}}
\begin{sphinxuseclass}{output_area}
\begin{sphinxuseclass}{}


\begin{sphinxVerbatim}[commandchars=\\\{\}]
\llap{\color{nbsphinxout}[2]:\,\hspace{\fboxrule}\hspace{\fboxsep}}<matplotlib.image.AxesImage at 0x125897010>
\end{sphinxVerbatim}



\end{sphinxuseclass}
\end{sphinxuseclass}
}

\end{sphinxuseclass}
\begin{sphinxuseclass}{nboutput}
\begin{sphinxuseclass}{nblast}
\hrule height -\fboxrule\relax
\vspace{\nbsphinxcodecellspacing}

\makeatletter\setbox\nbsphinxpromptbox\box\voidb@x\makeatother

\begin{nbsphinxfancyoutput}

\begin{sphinxuseclass}{output_area}
\begin{sphinxuseclass}{}
\noindent\sphinxincludegraphics[width=425\sphinxpxdimen,height=418\sphinxpxdimen]{{examples_example_3_1}.png}

\end{sphinxuseclass}
\end{sphinxuseclass}
\end{nbsphinxfancyoutput}

\end{sphinxuseclass}
\end{sphinxuseclass}
\sphinxAtStartPar
We then run pygenstability with the continuous\_combinatoral constructor, which corresponds to using the combinatorial Laplacian matrix in the Markov Stability. The number and range of markov times, or scales can be specified with max\_scale, min\_scale and n\_scales. They are in log scale by default. The number of Louvain evaluations is specified with n\_tries argument.

\sphinxAtStartPar
Other options are available, see the documentation: \sphinxurl{https://barahona-research-group.github.io/PyGenStability/}

\begin{sphinxuseclass}{nbinput}
{
\sphinxsetup{VerbatimColor={named}{nbsphinx-code-bg}}
\sphinxsetup{VerbatimBorderColor={named}{nbsphinx-code-border}}
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\llap{\color{nbsphinxin}[3]:\,\hspace{\fboxrule}\hspace{\fboxsep}}\PYG{c+c1}{\PYGZsh{} run markov stability and identify optimal scales}
\PYG{n}{results} \PYG{o}{=} \PYG{n}{pgs}\PYG{o}{.}\PYG{n}{run}\PYG{p}{(}
    \PYG{n}{sp}\PYG{o}{.}\PYG{n}{csgraph}\PYG{o}{.}\PYG{n}{csgraph\PYGZus{}from\PYGZus{}dense}\PYG{p}{(}\PYG{n}{A}\PYG{p}{)}\PYG{p}{,}
    \PYG{n}{min\PYGZus{}scale}\PYG{o}{=}\PYG{o}{\PYGZhy{}}\PYG{l+m+mf}{1.25}\PYG{p}{,}
    \PYG{n}{max\PYGZus{}scale}\PYG{o}{=}\PYG{l+m+mf}{0.75}\PYG{p}{,}
    \PYG{n}{n\PYGZus{}scale}\PYG{o}{=}\PYG{l+m+mi}{50}\PYG{p}{,}
    \PYG{n}{n\PYGZus{}tries}\PYG{o}{=}\PYG{l+m+mi}{20}\PYG{p}{,}
    \PYG{n}{constructor}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{continuous\PYGZus{}combinatorial}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{n\PYGZus{}workers}\PYG{o}{=}\PYG{l+m+mi}{4}
\PYG{p}{)}
\end{sphinxVerbatim}
}

\end{sphinxuseclass}
\begin{sphinxuseclass}{nboutput}
\begin{sphinxuseclass}{nblast}
{

\kern-\sphinxverbatimsmallskipamount\kern-\baselineskip
\kern+\FrameHeightAdjust\kern-\fboxrule
\vspace{\nbsphinxcodecellspacing}

\sphinxsetup{VerbatimColor={named}{nbsphinx-stderr}}
\sphinxsetup{VerbatimBorderColor={named}{nbsphinx-code-border}}
\begin{sphinxuseclass}{output_area}
\begin{sphinxuseclass}{stderr}


\begin{sphinxVerbatim}[commandchars=\\\{\}]
INFO:pygenstability.pygenstability:Precompute constructors{\ldots}
INFO:pygenstability.pygenstability:Optimise stability{\ldots}
INFO:pygenstability.pygenstability:Apply postprocessing{\ldots}
INFO:pygenstability.pygenstability:Compute ttprimes{\ldots}
INFO:pygenstability.pygenstability:Identify optimal scales{\ldots}
\end{sphinxVerbatim}



\end{sphinxuseclass}
\end{sphinxuseclass}
}

\end{sphinxuseclass}
\end{sphinxuseclass}
\sphinxAtStartPar
The standard plot to analyse multiscale clustering results in plot\_scan, which shows various informations, such as the number of cluster, stability, normalized variation of information (NVI) between Louvain evalutions, and accros scales (NVI(t, t’)). Finally, if computed a scale selection algorithm highlights most robust scales.

\begin{sphinxuseclass}{nbinput}
{
\sphinxsetup{VerbatimColor={named}{nbsphinx-code-bg}}
\sphinxsetup{VerbatimBorderColor={named}{nbsphinx-code-border}}
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\llap{\color{nbsphinxin}[4]:\,\hspace{\fboxrule}\hspace{\fboxsep}}\PYG{c+c1}{\PYGZsh{} plots results}
\PYG{n}{\PYGZus{}} \PYG{o}{=} \PYG{n}{plotting}\PYG{o}{.}\PYG{n}{plot\PYGZus{}scan}\PYG{p}{(}\PYG{n}{results}\PYG{p}{,} \PYG{n}{figure\PYGZus{}name}\PYG{o}{=}\PYG{k+kc}{None}\PYG{p}{)}
\end{sphinxVerbatim}
}

\end{sphinxuseclass}
\begin{sphinxuseclass}{nboutput}
\begin{sphinxuseclass}{nblast}
\hrule height -\fboxrule\relax
\vspace{\nbsphinxcodecellspacing}

\makeatletter\setbox\nbsphinxpromptbox\box\voidb@x\makeatother

\begin{nbsphinxfancyoutput}

\begin{sphinxuseclass}{output_area}
\begin{sphinxuseclass}{}
\noindent\sphinxincludegraphics[width=651\sphinxpxdimen,height=439\sphinxpxdimen]{{examples_example_7_0}.png}

\end{sphinxuseclass}
\end{sphinxuseclass}
\end{nbsphinxfancyoutput}

\end{sphinxuseclass}
\end{sphinxuseclass}
\sphinxAtStartPar
We can then plot the optimall partitions determined with the scale selection algorithm.

\begin{sphinxuseclass}{nbinput}
{
\sphinxsetup{VerbatimColor={named}{nbsphinx-code-bg}}
\sphinxsetup{VerbatimBorderColor={named}{nbsphinx-code-border}}
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\llap{\color{nbsphinxin}[7]:\,\hspace{\fboxrule}\hspace{\fboxsep}}\PYG{c+c1}{\PYGZsh{} plot optimal partitions}
\PYG{n}{plotting}\PYG{o}{.}\PYG{n}{plot\PYGZus{}optimal\PYGZus{}partitions}\PYG{p}{(}\PYG{n}{G}\PYG{p}{,} \PYG{n}{results}\PYG{p}{,} \PYG{n}{show}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{)}
\end{sphinxVerbatim}
}

\end{sphinxuseclass}
\begin{sphinxuseclass}{nboutput}
\hrule height -\fboxrule\relax
\vspace{\nbsphinxcodecellspacing}

\makeatletter\setbox\nbsphinxpromptbox\box\voidb@x\makeatother

\begin{nbsphinxfancyoutput}

\begin{sphinxuseclass}{output_area}
\begin{sphinxuseclass}{}
\noindent\sphinxincludegraphics[width=515\sphinxpxdimen,height=413\sphinxpxdimen]{{examples_example_9_0}.png}

\end{sphinxuseclass}
\end{sphinxuseclass}
\end{nbsphinxfancyoutput}

\end{sphinxuseclass}
\begin{sphinxuseclass}{nboutput}
\hrule height -\fboxrule\relax
\vspace{\nbsphinxcodecellspacing}

\makeatletter\setbox\nbsphinxpromptbox\box\voidb@x\makeatother

\begin{nbsphinxfancyoutput}

\begin{sphinxuseclass}{output_area}
\begin{sphinxuseclass}{}
\noindent\sphinxincludegraphics[width=515\sphinxpxdimen,height=413\sphinxpxdimen]{{examples_example_9_1}.png}

\end{sphinxuseclass}
\end{sphinxuseclass}
\end{nbsphinxfancyoutput}

\end{sphinxuseclass}
\begin{sphinxuseclass}{nboutput}
\begin{sphinxuseclass}{nblast}
\hrule height -\fboxrule\relax
\vspace{\nbsphinxcodecellspacing}

\makeatletter\setbox\nbsphinxpromptbox\box\voidb@x\makeatother

\begin{nbsphinxfancyoutput}

\begin{sphinxuseclass}{output_area}
\begin{sphinxuseclass}{}
\noindent\sphinxincludegraphics[width=515\sphinxpxdimen,height=413\sphinxpxdimen]{{examples_example_9_2}.png}

\end{sphinxuseclass}
\end{sphinxuseclass}
\end{nbsphinxfancyoutput}

\end{sphinxuseclass}
\end{sphinxuseclass}
\sphinxAtStartPar
Finally, we compare the selected partitions with the ground\sphinxhyphen{}truth planted partitions using the Normalised Variation of Information (NVI) and observe that MS analysis with optimal scale selection recovers the planted multiscale structure of the network.

\begin{sphinxuseclass}{nbinput}
{
\sphinxsetup{VerbatimColor={named}{nbsphinx-code-bg}}
\sphinxsetup{VerbatimBorderColor={named}{nbsphinx-code-border}}
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\llap{\color{nbsphinxin}[8]:\,\hspace{\fboxrule}\hspace{\fboxsep}}\PYG{c+c1}{\PYGZsh{} compare MS partitions to ground truth with NVI}
\PYG{k}{def} \PYG{n+nf}{\PYGZus{}get\PYGZus{}NVI}\PYG{p}{(}\PYG{n}{ref\PYGZus{}ids}\PYG{p}{)}\PYG{p}{:}
    \PYG{k}{return} \PYG{p}{[}
        \PYG{n}{evaluate\PYGZus{}NVI}\PYG{p}{(}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{,} \PYG{n}{i} \PYG{o}{+} \PYG{l+m+mi}{1}\PYG{p}{]}\PYG{p}{,} \PYG{p}{[}\PYG{n}{ref\PYGZus{}ids}\PYG{p}{]} \PYG{o}{+} \PYG{n}{results}\PYG{p}{[}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{community\PYGZus{}id}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{]}\PYG{p}{)}
        \PYG{k}{for} \PYG{n}{i} \PYG{o+ow}{in} \PYG{n+nb}{range}\PYG{p}{(}\PYG{n+nb}{len}\PYG{p}{(}\PYG{n}{results}\PYG{p}{[}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{scales}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{]}\PYG{p}{)}\PYG{p}{)}
    \PYG{p}{]}

\PYG{n}{NVI\PYGZus{}scores\PYGZus{}fine} \PYG{o}{=} \PYG{n}{\PYGZus{}get\PYGZus{}NVI}\PYG{p}{(}\PYG{n}{fine\PYGZus{}scale\PYGZus{}id}\PYG{p}{)}
\PYG{n}{NVI\PYGZus{}scores\PYGZus{}middle} \PYG{o}{=} \PYG{n}{\PYGZus{}get\PYGZus{}NVI}\PYG{p}{(}\PYG{n}{middle\PYGZus{}scale\PYGZus{}id}\PYG{p}{)}
\PYG{n}{NVI\PYGZus{}scores\PYGZus{}coarse} \PYG{o}{=} \PYG{n}{\PYGZus{}get\PYGZus{}NVI}\PYG{p}{(}\PYG{n}{coarse\PYGZus{}scale\PYGZus{}id}\PYG{p}{)}
\PYG{n}{scales} \PYG{o}{=} \PYG{n}{results}\PYG{p}{[}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{scales}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{]}

\PYG{c+c1}{\PYGZsh{} plot NVI scores}
\PYG{n}{fig}\PYG{p}{,} \PYG{n}{ax} \PYG{o}{=} \PYG{n}{plt}\PYG{o}{.}\PYG{n}{subplots}\PYG{p}{(}\PYG{l+m+mi}{1}\PYG{p}{,} \PYG{n}{figsize}\PYG{o}{=}\PYG{p}{(}\PYG{l+m+mi}{7}\PYG{p}{,} \PYG{l+m+mi}{4}\PYG{p}{)}\PYG{p}{)}
\PYG{n}{ax}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{n}{scales}\PYG{p}{,} \PYG{n}{NVI\PYGZus{}scores\PYGZus{}fine}\PYG{p}{,} \PYG{n}{label}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{Fine}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{)}
\PYG{n}{ax}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{n}{scales}\PYG{p}{,} \PYG{n}{NVI\PYGZus{}scores\PYGZus{}middle}\PYG{p}{,} \PYG{n}{label}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{Middle}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{)}
\PYG{n}{ax}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{n}{scales}\PYG{p}{,} \PYG{n}{NVI\PYGZus{}scores\PYGZus{}coarse}\PYG{p}{,} \PYG{n}{label}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{Coarse}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} plot selected partitions}
\PYG{n}{selected\PYGZus{}partitions} \PYG{o}{=} \PYG{n}{results}\PYG{p}{[}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{selected\PYGZus{}partitions}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{]}
\PYG{n}{ax}\PYG{o}{.}\PYG{n}{axvline}\PYG{p}{(}
    \PYG{n}{x}\PYG{o}{=}\PYG{n}{results}\PYG{p}{[}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{scales}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{]}\PYG{p}{[}\PYG{n}{selected\PYGZus{}partitions}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{p}{]}\PYG{p}{,}
    \PYG{n}{ls}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{\PYGZhy{}\PYGZhy{}}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{color}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{red}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{label}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{Selected Markov scales}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
\PYG{p}{)}
\PYG{k}{for} \PYG{n}{i} \PYG{o+ow}{in} \PYG{n}{selected\PYGZus{}partitions}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{:}\PYG{p}{]}\PYG{p}{:}
    \PYG{n}{ax}\PYG{o}{.}\PYG{n}{axvline}\PYG{p}{(}\PYG{n}{x}\PYG{o}{=}\PYG{n}{results}\PYG{p}{[}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{scales}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{]}\PYG{p}{[}\PYG{n}{i}\PYG{p}{]}\PYG{p}{,} \PYG{n}{ls}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{\PYGZhy{}\PYGZhy{}}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{color}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{red}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{)}

\PYG{n}{ax}\PYG{o}{.}\PYG{n}{set}\PYG{p}{(}\PYG{n}{xlabel}\PYG{o}{=}\PYG{l+s+sa}{r}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{\PYGZdl{}log\PYGZus{}}\PYG{l+s+si}{\PYGZob{}10\PYGZcb{}}\PYG{l+s+s2}{(t)\PYGZdl{}}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{ylabel}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{NVI}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{)}
\PYG{n}{plt}\PYG{o}{.}\PYG{n}{axhline}\PYG{p}{(}\PYG{l+m+mi}{0}\PYG{p}{,} \PYG{n}{c}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{k}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{ls}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{\PYGZhy{}\PYGZhy{}}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{)}
\PYG{n}{ax}\PYG{o}{.}\PYG{n}{legend}\PYG{p}{(}\PYG{n}{loc}\PYG{o}{=}\PYG{l+m+mi}{3}\PYG{p}{)}
\PYG{n}{plt}\PYG{o}{.}\PYG{n}{xscale}\PYG{p}{(}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{log}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{)}

\end{sphinxVerbatim}
}

\end{sphinxuseclass}
\begin{sphinxuseclass}{nboutput}
\begin{sphinxuseclass}{nblast}
\hrule height -\fboxrule\relax
\vspace{\nbsphinxcodecellspacing}

\makeatletter\setbox\nbsphinxpromptbox\box\voidb@x\makeatother

\begin{nbsphinxfancyoutput}

\begin{sphinxuseclass}{output_area}
\begin{sphinxuseclass}{}
\noindent\sphinxincludegraphics[width=613\sphinxpxdimen,height=379\sphinxpxdimen]{{examples_example_11_0}.png}

\end{sphinxuseclass}
\end{sphinxuseclass}
\end{nbsphinxfancyoutput}

\end{sphinxuseclass}
\end{sphinxuseclass}

\renewcommand{\indexname}{Python Module Index}
\begin{sphinxtheindex}
\let\bigletter\sphinxstyleindexlettergroup
\bigletter{p}
\item\relax\sphinxstyleindexentry{pygenstability.app}\sphinxstyleindexpageref{app:\detokenize{module-pygenstability.app}}
\item\relax\sphinxstyleindexentry{pygenstability.constructors}\sphinxstyleindexpageref{constructors:\detokenize{module-pygenstability.constructors}}
\item\relax\sphinxstyleindexentry{pygenstability.io}\sphinxstyleindexpageref{io:\detokenize{module-pygenstability.io}}
\item\relax\sphinxstyleindexentry{pygenstability.optimal\_scales}\sphinxstyleindexpageref{optimal_scales:\detokenize{module-pygenstability.optimal_scales}}
\item\relax\sphinxstyleindexentry{pygenstability.plotting}\sphinxstyleindexpageref{plotting:\detokenize{module-pygenstability.plotting}}
\item\relax\sphinxstyleindexentry{pygenstability.pygenstability}\sphinxstyleindexpageref{pygenstability:\detokenize{module-pygenstability.pygenstability}}
\end{sphinxtheindex}

\renewcommand{\indexname}{Index}
\printindex
\end{document}
