mlnlib 0.2.35__py3-none-any.whl

mlnlib/preparation.py

@@ -0,0 +1,517 @@
+"""
+Author: Eszter Bokanyi, 2023
+E-mail: e.bokanyi@uva.nl
+
+This file is created in the context of the POPNET project:
+https://popnet.io
+
+This script is able to prepare a multilayer network suitable for reading
+with mln.py from a very general set of CSV files.
+
+It accepts an arbitrary number of nodelist and edgelist CSV input files, reads through them,
+and merges the node properties, and converts the edgelists to a scipy.sparse adjacency matrix.
+The conversion happens through a layer.csv file, that contains the different linktypes and their
+binary representation. If no nodelist or layer file is given, these are inferred from the edgelist.
+
+Every input CSV is assumed to have a header and no index col.
+
+The config parameter colmap is a JSON file or a dict that maps the column names of the input files
+to the column names of the output files. If the map is empty ("none"), the column is dropped.
+
+The main node file is used to determine the node set, and the other node files are merged into it.
+
+The symmetrize parameters control whether the edgelists are symmetrized. If symmetrize_all is True,
+all layers are symmetrized, thus, the network is undirected. 
+Otherwise only the layers listed in symmetrize are symmetrized.
+
+The config file is a JSON file with the following structure:
+    
+    {
+        "node_conf": {
+            "input_folder_prefix": "",
+            "files": [],
+            "colmap": "",
+            "sep": ";",
+            "main_file": 0,
+            "output": ""
+        },
+        "edge_conf": {
+            "input_folder_prefix": "",
+            "files": [],
+            "colmap": "",
+            "sep": ";",
+            "output": ""
+        },
+        "layer_conf": {
+            "raw_file": "",
+            "file": "",
+            "output": "",
+            "symmetrize": [],
+            "symmetrize_all": False,
+            "raw_sep":",",
+            "sep": ",",
+            "colors": ""
+        },
+        "output_folder": ""
+    }
+
+The resulting files are saved to the output folder, if given, otherwise to the current directory:
+    * nodes.csv.gz: node dataframe
+    * edges.npz: adjacency matrix
+    * layers.csv: layer dataframe
+"""
+
+import pandas as pd
+from scipy.sparse import csr_matrix, save_npz
+import numpy as np
+
+import json
+import gc
+from time import sleep, time
+import sys
+
+# check whether we are in repo root, if not, change working directory
+import os
+if os.getcwd().endswith("src"):
+    os.chdir("..")
+
+print(f"We are currently working in the {os.getcwd()} directory.")
+
+class RawCSVtoMLN:
+    """
+    This class converts CSV nodelist and edgelist to fast readable input for the MLN class.
+
+    It accepts an arbitrary number of nodelist and edgelist CSV input files, reads through them,
+    and merges the node properties, and converts the edgelists to a scipy.sparse adjacency matrix
+    with integer elements that have a binary encoding for the layers.
+
+    Every input CSV is assumed to have a header and no index col.
+    """
+    def __init__(
+            self,
+            node_conf = dict(
+                input_folder_prefix = "",
+                files = [],
+                colmap = "",
+                sep = ";",
+                main_file = 0,
+                output = ""
+            ),
+            edge_conf = dict(
+                input_folder_prefix = "",
+                files = [],
+                colmap = "",
+                sep = ";",
+                output = ""
+            ),
+            layer_conf = dict(
+                raw_file = "",
+                file = "",
+                output = "",
+                symmetrize = [],
+                symmetrize_all = False,
+                raw_sep=",",
+                sep = ",",
+                colors = ""
+            ),
+            output_folder = "",
+            **kwargs
+        ):
+
+        self.node_conf = node_conf
+        self.edge_conf = edge_conf
+        self.layer_conf = layer_conf
+        self.output_folder = output_folder
+        self.grouped = False
+
+
+        # check if output folder is empty, if not, add / to end
+        if self.output_folder != "":
+            if not self.output_folder.endswith("/"):
+                self.output_folder += "/"
+        
+        # other kwargs
+        for (k, v) in kwargs.items():
+         setattr(self, k, v)
+
+    ###########################
+    ##### LAYERS    ###########
+    ###########################
+
+    def _open_file(self, read_func, *args, **kwargs):
+        success = 0
+        iter = 0
+        while not success and iter < 5:
+            try:
+                result = read_func(*args,**kwargs)
+                success = 1
+            except FileNotFoundError:
+                iter +=1
+        if success:
+            print(f"\tRead file on attempt no. {iter+1}.")
+        else:
+            raise FileNotFoundError("Could not read file in 5 attempts.")
+        return result
+            
+        
+    def init_layers(self):
+        """
+        Either read layer file, or create rich layer dataframe from bare minimum input.
+        """
+
+        # if the layer file is not yet prepared
+        if self.layer_conf["file"] == "":
+            print("Trying to create enriched layer dataframe...")
+            # there should at least be a very basic layer file (e.g. prepared from the edgelists, if nothing else)
+            if self.layer_conf["raw_file"]=="":
+                self.init_raw_layers_from_edges()
+            else:
+                print("\tReading raw layer input file...")
+                self.layers = self._open_file(
+                    pd.read_csv,
+                    self.layer_conf["input_folder_prefix"] + self.layer_conf["raw_file"],
+                    index_col=None,
+                    header=0,
+                    sep=self.layer_conf["raw_sep"]
+                )
+            # if we want to rename columns, there's either a JSON or a dict
+            if self.layer_conf["colmap"] != "":
+                print("\tRenaming layer dataframe columns...")
+                if type(self.layer_conf["colmap"]) == str:
+                    self.layer_conf["colmap"] = json.load(open(self.layer_conf["colmap"]))
+                print(json.dumps(self.layer_conf["colmap"],indent="\t\t"))
+                self.layers.rename(columns = self.layer_conf["colmap"], inplace = True)
+
+            print("\tAdding binary representation, groups and long labels...")
+            if self.grouped:
+                grps = dict(zip(self.layers["group_layer"],self.layers["group_label"]))
+                self.layers_ungrouped = self.layers
+                self.layer_mapping = dict(zip(self.layers_ungrouped["layer"],self.layers_ungrouped["group_layer"]))
+                self.layers = pd.DataFrame(np.array([list(grps.keys()),list(grps.values())]).T,columns = ["layer","label"])
+            # creating different 2**i numbers for all linktypes for binary encoding
+            self.layers["binary"] = self.layers.index.map(lambda i: int(2**i))
+            if "group" not in self.layers:
+                self.layers["group"] = self.layers["label"]
+            # creating long labels for layers for visualizations etc.
+            self.layers["label_long"] = self.layers.apply(lambda row: row['group']+": "+row["label"], axis=1)
+            # layer_group -> integer representations: summing up all binary numbers corresponding to a certain group
+            self.layer_group_binary = self.layers.groupby("group").sum()["binary"].map(int).to_dict()
+
+            # adding group colors
+            if self.layer_conf["colors"]!="":
+                print("\tAdding colors...")
+                if type(self.layer_conf["colors"]) == str:
+                    self.layer_conf["colors"] = json.load(open(self.layer_conf["colors"]))
+                # print(json.dumps(self.layer_conf["colors"],indent="\t\t"))
+                self.layers["color"] = self.layers["group"].map(self.layer_conf["colors"])
+            # exporting
+            self.layer_conf["file"] = self.output_folder + self.layer_conf["output"]
+            self.layers.to_csv(self.layer_conf["file"],index=False,header=True)
+        
+        print("Done.")
+        print("Reading " + self.layer_conf["file"] + "...")
+        self.layers = pd.read_csv(self.layer_conf["file"], index_col = None, header=0)
+        print("Layer dataframe",self.layers.head(),self.layers.columns,end="\n")
+
+    def init_raw_layers_from_edges(self):
+        """
+        This function reads the raw edgelist file and creates a layer dataframe
+        from the different linktypes.
+        """
+        raise ValueError("To initialize layers from edgelist is not yet done.")
+        # getting all layer types
+        layers = self.edgelist["layer"].unique()
+        # creating layer dataframe
+        self.layers = pd.DataFrame({"label": layers, "layer": layers})
+
+    ###########################
+    ##### NODES    ############
+    ###########################
+
+    # Loading node attributes files
+    # =============================
+    def init_nodes(self):
+        """
+        Read node dataframe from node_conf["files"]. If node_conf["files"] is empty,
+        create a node dataframe from the edgelist.
+        """
+        print("Creating merged node attribute file...")
+
+        if self.node_conf["colmap"] != "":
+            if type(self.node_conf["colmap"]) == str:
+                self.node_conf["colmap"] = json.load(open(self.node_conf["colmap"]))
+        
+        def get_node_file(p):
+            # add input folder prefix from node_conf if given
+            if self.node_conf["input_folder_prefix"] != "":
+                if not self.node_conf["input_folder_prefix"].endswith("/"):
+                    self.node_conf["input_folder_prefix"] += "/"
+                p = self.node_conf["input_folder_prefix"] + p
+
+            print(f"Reading file {p}...")
+            if p.endswith('gz'):
+                node_df = self._open_file(pd.read_csv,p,sep=self.node_conf["sep"],index_col=None,compression='gzip')#,nrows=10)
+            elif p.endswith('sav'):
+                node_df = self._open_file(pd.read_spss,p,usecols = self.node_conf["colmap"].keys(),convert_categoricals=False)
+            else:
+                node_df = self._open_file(pd.read_csv,p,sep=self.node_conf["sep"],index_col=None)#,nrows=10)
+            if self.node_conf["colmap"] != "":
+                for c in node_df.columns:
+                    if c not in self.node_conf["colmap"]:
+                        node_df.drop(c,axis=1,inplace=True)
+                node_df.rename(columns = self.node_conf["colmap"],inplace=True)
+            print(node_df.head())
+            node_df.set_index("label",inplace=True)
+            return node_df
+        
+        if self.node_conf["files"]!="":
+            print("Merging all node files...")
+            # TODO: check for joins, we might lose some lines here!
+            nodes = pd.concat([get_node_file(f) for f in self.node_conf["files"]], axis=1)     
+
+            # make label a column
+            nodes.reset_index(inplace=True) 
+            if "id" not in nodes.columns:
+                # add ids if they don't exist
+                nodes.reset_index(inplace=True)
+                # renaming columns to human readable and consistency
+                nodes.rename(columns={"index":"id"},inplace=True)
+
+            self.nodes = nodes
+            print("Initialized node dataframe.")
+        else:
+            raise ValueError("To initialize nodelist from edgelist is not yet done.")
+
+    ###########################
+    ##### EDGES    ############
+    ###########################
+
+    def init_edges(self):
+        # getting id <-> label mappings
+        self.nodemap_back = dict(zip(self.nodes["id"], self.nodes['label']))
+        self.nodemap = {v:k for k,v in self.nodemap_back.items()}
+
+        self.N = len(self.nodemap.keys())
+        print(f"N is {self.N}")
+        self.A = csr_matrix((self.N,self.N), dtype=np.uint64)
+    
+    def adjacency_matrix(self, edgelist, binary, symmetrize=False):
+        """
+        This function creates the adjacency matrix representation of a graph
+        based on a pandas.DataFrame edgelist. The edgelist should be a plain array.
+
+        Returns
+        -------
+
+        A : scipy.sparse.csr_matrix
+            sparse adjacency matrix
+        """
+        # remapping labels to integer ids from 0 to N-1 to load into sparse CSR matrix
+        i = pd.Series(map(lambda x: self.nodemap.get(x),edgelist["source"]))
+        j = pd.Series(map(lambda x: self.nodemap.get(x),edgelist["target"]))
+
+        in_nodelist = ~pd.isnull(i)&~pd.isnull(j)
+        i = i[in_nodelist]
+        j = j[in_nodelist]
+
+        # if creating / enforcing undirected graph
+        if symmetrize:
+            sym_i = i+j
+            sym_j = j+i
+            i = sym_i
+            del sym_i
+            j = sym_j
+            del sym_j
+        
+        A = csr_matrix((np.ones(len(i)),(i,j)), shape=(self.N,self.N), dtype = np.uint64)
+        if symmetrize:
+            A = csr_matrix(A>0, dtype=np.uint64)
+        #  we multiply to 1/0 matrix by that number so that it corresponds to a certain edgetype
+        A *= binary
+
+        return A
+    
+    def _print_size(self,var,name=""):
+        """
+        Prints variable size in GB to allow for memory control.
+        """
+        print(f"{name}: {round(sys.getsizeof(var)/1024**3,2)}GB")
+
+    def read_all_edges(self):
+        """
+        This function loads all edgelists for the
+        different linktypes of the different layers, and subsequently
+        adds 2**i to the adjacency matrix for the edges, where 2**i corresponds
+        to the type of the edge from self.layers["binary"].
+        In the end, the function saves the scipy.sparse.csr_matrix type
+        adjacency matrix to the given location
+        """
+
+        # check if symmetrize_all in layer_conf is str
+        if type(self.layer_conf["symmetrize_all"]) == str:
+            # if "true" or "false", set to boolean
+            if self.layer_conf["symmetrize_all"].lower() == "true":
+                self.layer_conf["symmetrize_all"] = True
+            elif self.layer_conf["symmetrize_all"].lower() == "false":
+                self.layer_conf["symmetrize_all"] = False
+            else:
+                raise ValueError("symmetrize_all in layer_conf is not a boolean value.")
+        
+        # if symmetrize_all is True, add all layers to symmetrize list
+        if self.layer_conf["symmetrize_all"]:
+            self.layer_conf["symmetrize"] = self.layers["layer"].tolist()
+
+        if self.grouped:
+            l_list = self.layers_ungrouped["layer"]
+        else:
+            l_list = self.layers["layer"]
+
+        # get chunks of the edgelist
+        if self.edge_conf["colmap"] != "":
+            if type(self.edge_conf["colmap"]) == str:
+                self.edge_conf["colmap"] = json.load(open(self.edge_conf["colmap"]))
+
+        if self.edge_conf["input_folder_prefix"] != "":
+            if not self.edge_conf["input_folder_prefix"].endswith("/"):
+                self.edge_conf["input_folder_prefix"] += "/"
+                for i in range(len(self.edge_conf["files"])):
+                    self.edge_conf["files"][i] = self.edge_conf["input_folder_prefix"] + self.edge_conf["files"][i]
+
+        # START HEAVY PART
+        chunksize = int(2e8)
+
+        # read all edge files
+        for ef in self.edge_conf["files"]:
+            print(f"Reading edge file {ef}...")
+            # loading file in chunks
+            print("\tLoading file in chunks...")
+            tic  = time()
+            iter = 0
+            with self._open_file(pd.read_csv,ef, sep=self.edge_conf["sep"],header=0,chunksize=chunksize) as reader:
+                # for all chunks
+                for chunk in reader:
+                    iter += 1
+                    self._print_size(chunk,"\tSize of current chunk")
+                    print(f"\tChunk no. {iter}")
+                    if self.edge_conf["colmap"]!="":
+                        for k,v in self.edge_conf["colmap"].items():
+                            if v == None and k in chunk.columns:
+                                chunk.drop(k,inplace=True,axis=1)
+                            else:
+                                chunk.rename(columns = {k:v},inplace=True)
+
+                    # make sure node labels are integers for the mapping to work
+                    if chunk["source"].dtype!=int:
+                        chunk["source"] = chunk["source"].map(int)
+                    if chunk["target"].dtype!=int:
+                        chunk["target"] = chunk["target"].map(int)
+
+                    # check for layers in chunk and add them to adjacency matrix
+                    for l in l_list:
+                        if not self.grouped:
+                            layer = l
+                        else:
+                            layer = self.layer_mapping[l]
+                        # linktype name
+                        name = self.layers.set_index("layer").loc[layer]["label_long"]
+                        binary = self.layers.set_index("layer").loc[layer]["binary"]
+                        selection = chunk["layer"]==l
+                        num_edges = (selection).sum()
+                        # contains values of binary_linktype / 0
+                        if num_edges>0:
+                            A = self.adjacency_matrix(chunk[selection], binary, symmetrize=layer in self.layer_conf["symmetrize"])
+                            print(f"\tAdding {A.nnz} edges to layer {layer}.")
+                            self.A += A
+                            print("\tNumber of nonzero edges in full adjacency matrix:",self.A.nnz)
+                            #temp = dict(zip(zip(*A.nonzero()),A.data))
+                            #print("temp",temp)
+                            #self.A_dict = {
+                            #    key: self.A_dict.get(key,0) | temp.get(key,0) for key in set(self.A_dict.keys()) | temp.keys()
+                            #}
+                            #print("A_dict",self.A_dict)
+                            # cleaning memory of large unnecessary objects
+                            del A#,temp
+            toc = time()
+            print(f"\tFinished with chunk in {round(toc-tic,1)}s.")
+            tic = toc
+
+        #data = list(self.A_dict.values())
+        #i = [elem[0] for elem in self.A_dict.keys()]
+        #j = [elem[1] for elem in self.A_dict.keys()]
+        #self.A = csr_matrix((data,(i,j)),shape=(self.N,self.N),dtype='int8')
+        #del self.A_dict,i,j,data
+
+
+    def init_all(self):
+        """
+        Read all components given in config, and save results to output folder if necessary.
+        """
+        self.init_layers()
+        print(f"LAYERS: {self.layers.shape[0]}")
+        self.init_nodes()
+        print(f"NODES: {self.nodes.shape[0]}")
+        self.init_edges()
+        self.read_all_edges()
+        print(f"EDGES: {self.A.nnz}")
+
+        if "save" in self.__dict__:
+            if self.save:
+                self.save_all()
+
+    def save_layer_df(self, output):
+        print("Saving layer dataframe...")
+        self.layers.to_csv(output,index=False,header=True)
+        print("Done.")
+    
+    def save_node_df(self, output):
+        print("Saving node dataframe...")
+        self.nodes.to_csv(output,index=False,header=True,compression="gzip")
+        print("Done.")
+
+    def save_edge_npz(self, output):
+        print("Saving edge adjacency matrix...")
+        save_npz(output, self.A)
+        print("Done.")
+
+    def save_all(self, overwrite = False):
+        # if overwrite in attributes, set overwrite
+        if "overwrite" in self.__dict__:
+            overwrite = self.overwrite
+        # check if output_folder is given and give warning if not
+        if self.output_folder== "":
+            print("WARNING: No output folder given, saving to current directory.")
+        else:
+            # check if output folder has an ending / and add it if not
+            if not self.output_folder.endswith("/"):
+                self.output_folder += "/"
+            # check if output folder exists, if not, create it
+            if not os.path.isdir(self.output_folder):
+                os.mkdir(self.output_folder)
+
+
+        print("Writing node, layer and edge files...")
+
+        if self.layer_conf["output"]=="": self.layer_conf["output"] = "layers.csv"
+        # check if the above file exists, if overwrite=False, raise error
+        if os.path.isfile(self.output_folder + self.layer_conf["output"]) and not overwrite:
+            raise ValueError("Layer file already exists, please specify overwrite=True in config file.")
+        print("Writing layer file to " + self.output_folder + self.layer_conf["output"] + "...")
+        self.save_layer_df(self.output_folder + self.layer_conf["output"])
+        print("Done")
+        
+        if self.node_conf["output"]=="": self.node_conf["output"] = "nodes.csv.gz"
+        # check if the above file exists, if overwrite=False, raise error
+        if os.path.isfile(self.output_folder + self.node_conf["output"]) and not overwrite:
+            raise ValueError("Node file already exists, please specify overwrite=True in config file.")
+        print("Writing node file to " + self.output_folder + self.node_conf["output"] + "...")
+        self.save_node_df(self.output_folder + self.node_conf["output"])
+        print("Done.")
+        
+        if self.edge_conf["output"]=="": self.edge_conf["output"] = "edges.npz"
+        # check if the above file exists, if overwrite=False, raise error
+        if os.path.isfile(self.output_folder + self.edge_conf["output"]) and not overwrite:
+            raise ValueError("Edge file already exists, please specify overwrite=True in config file.")
+        print("Writing edge file to " + self.output_folder + self.edge_conf["output"] + "...")
+        self.save_edge_npz(self.output_folder + self.edge_conf["output"])
+        print("Done.")
+

mlnlib-0.2.35.dist-info/LICENSE.md

@@ -0,0 +1,40 @@
+### MIT License
+
+Copyright (c) 2024 Eszter Bokányi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+In any academic work, the package should be cited as follows:
+
+Bokányi, E., Kazmina, Y., & de Jong, R. (2023). POPNET MultiLayerNetwork Python Class (Version v2.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.10838865
+
+The BibTeX entry for the citation is:
+```
+@software{bokanyi2023popnet,
+  title = {{{POPNET MultiLayerNetwork Python Class}}},
+  author = {Bok\'anyi, Eszter and Kazmina, Yuliia and family=Jong, given=Rachel, prefix=de, useprefix=true},
+  date = {2023},
+  doi = {10.5281/zenodo.10838865},
+  url = {https://zenodo.org/doi/10.5281/zenodo.10838865},
+  urldate = {2024-11-11},
+  abstract = {Library for working with large multilayer networks by the POPNET group.},
+  organization = {Zenodo},
+  version = {v2.0}
+}
+```
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mlnlib-0.2.35.dist-info/METADATA

@@ -0,0 +1,126 @@
+Metadata-Version: 2.1
+Name: mlnlib
+Version: 0.2.35
+Summary: Memory-efficient library for loading and working with large unweighted multilayer networks.
+Author-email: Eszter Bokányi <e.bokanyi@uva.nl>
+Project-URL: Homepage, https://github.com/popnet-io/popnet_mln
+Project-URL: Issues, https://github.com/popnet-io/popnet_mln/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: pandas >=1.4.4
+Requires-Dist: polars >=0.20.6
+Requires-Dist: numpy >=1.20.3
+Requires-Dist: python-igraph >=0.9.9
+Requires-Dist: networkx >=3.0
+Requires-Dist: scipy >=1.10.1
+
+# MLN
+
+Library for working with large multilayer networks.
+
+Authors:
+* Eszter Bokányi
+* Rachel de Jong
+* Yuliia Kazmina
+
+Contact:
+`e.bokanyi@uva.nl`
+
+The code is distirbuted under the MIT Licence and should be properly attributed and cited upon reuse - see LICENCE.md for details.
+
+## MultiLayeredNetwork class
+
+The `MultiLayeredNetwork` class from `src/mln.py` contains methods and attributes to work with a large
+multilayer network using different edge types and layers efficiently.
+
+The network has to be unweighted, but can be directed.
+
+The network is either loaded from an already saved sparse matrix and a
+node attribute CSV using the following attributes:
+* adjacency_file:  scipy.sparse.csr matrix saved as an `npz` file
+* node_attribute_file: CSV to be loaded as a pd.DataFrame, rows in
+    order of previous matrix rows should contain a column called
+    "label" that is the primary key for node identification
+
+Or in-memory objects can also be given to the constructor:
+* adjacency_matrix: scipy.sparse.csr matrix
+* node_attribute_dataframe: pd.DataFrame, rows in order of previous
+    matrix rows
+
+Pre-stored files with standard names can be called with the shorthand:
+* from_library: str
+Then the npz and csv.gz files will be read from the
+library_path/from_library folder similarly to the first method.
+
+After loading these two key elements, class attributes and methods work
+the same.
+
+The adjacency matrix self.A is stored in a `scipy.sparse.csr_matrix`
+class, that only saves nonzero elements, and on which scipy csgraph
+algorithms run. People are indexed from 0 to N-1, where N is the total
+number of nodes in this network.
+
+Two dictionaries mapping user id (label) to integer node ids (NID) and
+back are created based on the node attribute file in the
+`self.map_label_to_nid` and `self.map_nid_to_label` attributes. These
+mappings only refer to one instance of the class - if you create a
+subgraph (see later) the coding is going to change, and the mapping
+should be found in the new instance that represents the subgraph.
+
+The adjacency matrix contains integers that encode linktypes if viewed
+as binary numbers. Each possible linktype is assigned an integer of the
+form 2\**i. For example, if both type i and type j edge is present
+between two people, then the corresponding value in self.A would be
+2\**i+2\**j. It means that we can test for a certain edgetype using
+bitwise AND operation very cheaply. E.g. a certain element of self.A is
+7, then 7=1+2+4 which means that edgetypes 0,1, and 2 are present
+between the two people, and 7&2 = 2 in Python (it behaves like a mask
+111 & 010 = 010).
+
+scipy.csr matrices are cheap to slice rowwise, but beware, some
+operation that seem straightforward in numpy might be costly (e.g.
+getting random coordinates after each other or colwise slicing)! If
+something is running too long, consult the scipy reference manual.
+
+Node attributes are stored in `self.node_attributes` which is a
+`pandas.DataFrame`. It is possible to store human-readable or longer
+column names in `self.attribute_colnames`, and code tables for used
+variables in  `self.attribute_code_table`, keys of that variable are the
+colnames in the values of `self.attribute_colnames`.
+
+Example loadings:
+
+```
+# FROM FILES
+# import custom class for the network from mln
+import MultiLayeredNetwork
+
+# read the whole network
+popnet = MultiLayeredNetwork(
+    adjacency_file = 'path_to/adjacency.npz',
+    node_attribute_file = 'path_to/attributes.csv.gz'
+)
+
+# FROM MEMORY
+# import custom class for the network
+from mln import MultiLayeredNetwork
+
+# read the whole network
+popnet = MultiLayeredNetwork(
+    adjacency_matrix = A, # NxN scipy.sparse.csr_matrix
+    node_attribute_file = df # pd.DataFrame containing N rows in the order of the matrix
+)
+
+# FROM LIBRARY
+# import custom class for the network
+from mln import MultiLayeredNetwork
+
+# read the whole network
+popnet = MultiLayeredNetwork(
+    from_library="full"
+)
+```