Package: oslom-runner
python-oslom-runnerAn OSLOM Runner for Python.OSLOMstands forOrder Statistics Local Optimization Methodand it's a clustering algorithm designed for networks.You can obtain a copy of OSLOM from:http://www.oslom.org/More information on OSLOM can be found in the following publication:Lancichinetti, Andrea, et al. "Finding Statistically Significant Communities in Networks." PloS one 6.4 (2011): e18961.InstallationYou can usepip(or anyPyPi-compatible package manager) for installation:pip install oslom-runneror, if you prefer a local user installation:pip install --user oslom-runnerUsageFirst, make sure you have a working copy of OSLOM installed. OSLOM version 2 is strongly recommended as it is faster with very similar clustering performance.To use this runner you will need an input file with network edges in the same format OSLOM expects (source,target,weight).The fields in this file must beTABseparated. For example:100 \t 200 \t 1
200 \t 500 \t 1
100 \t 500 \t 8NOTE:OSLOM only supports 32-bits signed integers for node identifiers, however this runner supports string-based identifiers that are automatically re-mapped to the supported integers before calling OSLOM. Therefore, the number ofunique string identifiersis still limited to2^31 - 1. An example edges file with string identifiers can be seen below:NodeA \t NodeB \t 1
NodeB \t NodeC \t 1
NodeA \t NodeC \t 8You can then run OSLOM over the network using the following command:oslom-runner --edges myedges.tsv \
    --output-clusters clusters.json \
    --oslom-output oslom-filesAfter execution you will get a JSON formatted file with the clusters found by OSLOM from the provided network edges file.This OSLOM Runner supports the following command line options:--edges: the network edges file in TSV (Tab-separated values) format.--output-clusters: the found clusters output file in JSON format.--oslom-output: the output directory to put resulting OSLOM files.--min-cluster-size: the minimum cluster size for filtering after running OSLOM. Default:0.--oslom-exec: the path (absolute or relative) to the OSLOM executable to invoke. Default:oslom_dir. You can use OSLOM in directed or undirected mode. See theOSLOM documentationfor more information.Finally, you can also pass custom OSLOM arguments (with the exception of the-foption!) after all options to the runner using the following command:oslom-runner --edges myedges.tsv \
    --output-clusters clusters.json \
    --oslom-output oslom-files \
    --oslom-exec /opt/oslom/oslom2_dir \
    -- -hr 1 -r 1Please note the usage of double dashes (--) to separate the runner's own arguments from the OSLOM native ones.The default arguments used for OSLOM are-w -r 10 -hr 10, which sets the usage of a weighted network and 10 computation iterations for first and higher hierarchical levels respectively.When you pass your own OSLOM arguments, none of the default options will be used. You shouldNEVERgive the-foption because the runner automatically fills the value for it accordingly.Using ProgramaticallyThis OSLOM Runner can be used programatically inside your own Python scripts as well.There are two main functions to run OSLOM, both using nearly the same arguments:run(): reads input edges and writes output clusters directly on disk. Also outputs OSLOM auxiliary files to a given directory. This is the function used by the command-line interface.run_in_memory(): similar torun()but takes edges from a Python iterable and provides the clusters in a dictionary instead of files on disk. This function does not keep OSLOM auxiliary files. This function is useful for avoiding manual reading/writing of data on disk from your scripts.The arguments for these functions must be aNamespaceobject from theargparsemodule. A working example for both functions is below:fromargparseimportNamespaceimportoslom# run OSLOM with files already on diskargs=Namespace()args.edges="/path/to/input_edges.tsv"args.output_clusters="/path/to/output_clusters.json"args.oslom_output="/path/to/oslom_aux_files"args.min_cluster_size=oslom.DEF_MIN_CLUSTER_SIZEargs.oslom_exec=oslom.DEF_OSLOM_EXECargs.oslom_args=oslom.DEF_OSLOM_ARGSoslom.run(args)# run OSLOM with data in Python objectsargs=Namespace()args.min_cluster_size=0args.oslom_exec=oslom.DEF_OSLOM_EXECargs.oslom_args=oslom.DEF_OSLOM_ARGS# edges is an iterable of tuples (source, target, weight)# in the same format as the command-line versionedges=[(0,1,1.0),(1,2,1),(2,0,1)]clusters=oslom.run_in_memory(args,edges)print(clusters)LicenseThis software is under theApache License 2.0.Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.