caryocar 0.0.1
A Python package for building SCN and CWN models.

Caryocar
========

Caryocar is a Python package for building Species-Collector Networks (SCNs) and Collector CoWorking Networks(CWNs) models from species occurrence data, as introduced in my [MSc thesis](https://lncc-netsci.github.io/pedrocs/).
SCNs and CWNs extend the social network analytics and can be used for understanding the social structure behind biological collections.
This package is built on top of [NetworkX](https://github.com/networkx/networkx).


### Supporting documents
* New perspectives on analyzing data from biological collections based on social network analytics [[MSc thesis](https://tede.lncc.br/handle/tede/279)].
* On the social structure behind biological collections [[Preprint](https://www.biorxiv.org/content/early/2018/06/08/341297)].
* Package documentation coming soon...


Example Usage
-------------
Create a Species-Collector Network (SCN) from a list of collectors and species:

    >>> cols=[ ['col1','col2','col3'],
               ['col1','col2'],
               ['col2','col3'],
               ['col4','col5'],
               ['col4'],
               ['col5','col4'] ]

    >>> spp=['sp1','sp2','sp3','sp2','sp3','sp2']

    >>> scn = SpeciesCollectorsNetwork( species=spp, collectors=cols )

    >>> scn.nodes(data=True)
    { 'sp1': {'bipartite': 1, 'count': 1}, 
      'col1': {'bipartite': 0, 'count': 2}, 
      'col2': {'bipartite': 0, 'count': 3}, 
      'col3': {'bipartite': 0, 'count': 2}, 
      'sp2': {'bipartite': 1, 'count': 3}, 
      'sp3': {'bipartite': 1, 'count': 2}, 
      'col4': {'bipartite': 0, 'count': 3}, 
      'col5': {'bipartite': 0, 'count': 2} }

    >>> scn.edges(data=True)
    [ ('sp1', 'col1', {'count': 1}), 
      ('sp1', 'col2', {'count': 1}), 
      ('sp1', 'col3', {'count': 1}), 
      ('col1', 'sp2', {'count': 1}), 
      ('col2', 'sp2', {'count': 1}), 
      ('col2', 'sp3', {'count': 1}), 
      ('col3', 'sp3', {'count': 1}), 
      ('sp2', 'col4', {'count': 2}), 
      ('sp2', 'col5', {'count': 2}), 
      ('sp3', 'col4', {'count': 1}) ]    



Create a Collector CoWorking Network (CWN) from a list of collector cliques:

		>>> collectors = [ ['a','b','c'], ['d','e'], ['a','c'] ]
    >>> cwn = CoworkingNetwork(cliques=collectors)

    >>> cwn.nodes(data=True)
    { 'a': {'count': 2}, 
      'b': {'count': 1}, 
      'c': {'count': 2}, 
      'd': {'count': 1}, 
      'e': {'count': 1} }    

    >>> cwn.edges(data=True)
    [ ('a', 'b', {'count': 1, 'taxons': None, 'weight_hyperbolic': 0.5}), 
      ('a', 'c', {'count': 2, 'taxons': None, 'weight_hyperbolic': 1.5}), 
      ('b', 'c', {'count': 1, 'taxons': None, 'weight_hyperbolic': 0.5}), 
      ('d', 'e', {'count': 1, 'taxons': None, 'weight_hyperbolic': 1.0}) ]


Install
-------

This package is still experimental, and should ideally be run from a conda virtual environment, which is specified in the `environment.yml` file. In order to create the virtual environment clone this repository, make sure you have [conda](https://conda.io/docs/) installed and use one of the following commands, from the root of the repository:

    $ conda env create -f environment.yml

Then you should activate it with the following command:

* On Linux:


    $ source activate caryocar


* On Windows:


    $ activate caryocar