Metadata-Version: 2.1
Name: ugd
Version: 0.0.9
Summary: drawing uniformly graphs under constraint. Commonly used for the estimation of the test distribution
Home-page: UNKNOWN
Author: Andrin Pelican
Author-email: andrin.pelican@student.unisg.ch
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: matplotlib

# Uniform Graph Draw

*currently in production*

This package implements random draw algorithm for networks. In particular it creates uniform samples of networks with a
given degree-sequence and further constraints (fixed number of crossing edges/arrows between node-groups) 


It is implement according to the papers:

- ...


The papers also include a proof of correctness and a discussion of the statistical background. 

## Get it running 

Install the paper via pip:


- pip install ugd

then run

    #import modules
    import ugd
    import numpy

    # create ajdancy matrix
    adj_m = numpy.zeros((4,4))
    adj_m[0,1] = 1
    adj_m[1,0] = 1
    adj_m[3,2] = 1
    adj_m[2,3] = 1

    # create dictionary of nodeatributes 
    var_dict ={
        0: {'gender': 'm'},
        1: {'gender': 'm'},
        2: {'gender': 'f'},
        3: {'gender': 'f'},
    }
    graphs, stats_list = ugd.graph_hyp_test(adj_m=adj_m, var_dict = var_dict, test_variable= ('gender','m','f'),mixing_time=1000, anz_sim=100, show_polt=True)


## API

There are two functions provided.

1) graph_hyp_test
    - generating a sequence of uniform sampled *graphs* under the desired set of constrains.
2) digraph_hyp_test
    - generating a sequence of uniform sampled *digraphs* under the desired set of constrains.

For the API fo the two functions only differs in that the interpretation of the adjancy matrix is once 
as digraph representation and once as graph representation.



    INPUT:
    :param adj_m:         A numpy array containing 0 and 1s as elements, representing
                          adjacency matrix of the graph
    :param var_dict:      A dictionary with the integers 1..n as primary key (representing
                          the n nodes). The values are dictionaries containing the 
                          Variable name as keys and the values can either be numbers or be
                          numbers or strings
    :param stat_f:        A function which maps the adj_m and var_dict to a number "the
                          statistic of interest".
    :param test_variable: alternative to stat_f, creating a statistic which counts the
                          arrows form a node-subset into another. It is a triple with 
                          first element variable name, second the value of the variable 
                          for the set where the arrows leave and third the value of the 
                          subset where the arrow go to.
    :param controlls:     List of variable names, the number of arrows crossing the groups
                          induced by the controls is constant in all the simulation.
    :param mixing_time:   Number of runs (steps in the markov graph) before a the graph
                          is considered random
    :param anz_sim:       Number of simulations
    :param show_polt:     Boolean whether a plot is desired

    OUTPUT:
    :return:
    graph_list:           List of random adjacency matrices with the given degree-sequence
                          and arrows between the controls
    stats_list:           List of the statistics stat_f evaluated for the random graphs



**Comment:**

The current implementation, includes only controlling of a fixed number of crossing edges/arrows between node-groups as 
constraints. More complex complex can be implemented by writing a consum implementation of the *no_violation* function 
in *constraint_violation_check*. Note, that depending on the constraint the construction of the Schlaufensequence should
 not be stopped because a feasible one is found, but only due to the random stop. This in order to preserve correctness.



## Architecture:


All the logic is implemented in the digraph_draw folder. it is divided into

*  markow_walk

      Implementation of algorithm 1 from the paper ....

* schlaufen_construction

     Implementation of algorithm 2 from the paper ....


*  model

    containing the data models (appropriate Graph representation  and node representation for 
    efficient construction of the altering paths in the Schlaufen)

* user_interface

    Contains the all the logic used for *input validation, parsing of input, estimation of runtime, 
    transformation of the graph format, output processing*.

*  help_functions


## Testing

All tests are in the test folder. They are written using pytest. 
To execute them cd into the test folder and run

- pytest 

in the terminal.










