{
    "info": {
        "author": "Hugo Hromic",
        "author_email": "hhromic@gmail.com",
        "bugtrack_url": null,
        "classifiers": [
            "Environment :: Console"
        ],
        "description": "# python-oslom-runner\n\nAn OSLOM Runner for Python. *OSLOM* stands for *Order Statistics Local Optimization Method* and it's a clustering algorithm designed for networks.\n\nYou can obtain a copy of OSLOM from: <http://www.oslom.org/>\n\nMore information on OSLOM can be found in the following publication:\n\n> Lancichinetti, Andrea, et al. \"Finding Statistically Significant Communities in Networks.\" PloS one 6.4 (2011): e18961.\n\n## Installation\n\nYou can use `pip` (or any `PyPi`-compatible package manager) for installation:\n\n    pip install oslom-runner\n\nor, if you prefer a local user installation:\n\n    pip install --user oslom-runner\n\n## Usage\n\nFirst, 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.\n\nTo use this runner you will need an input file with network edges in the same format OSLOM expects (`source`, `target`, `weight`).\n\nThe fields in this file must be `TAB` separated. For example:\n\n    100 \\t 200 \\t 1\n    200 \\t 500 \\t 1\n    100 \\t 500 \\t 8\n\n**NOTE:** 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 of **unique string identifiers** is still limited to `2^31 - 1`. An example edges file with string identifiers can be seen below:\n\n    NodeA \\t NodeB \\t 1\n    NodeB \\t NodeC \\t 1\n    NodeA \\t NodeC \\t 8\n\nYou can then run OSLOM over the network using the following command:\n\n    oslom-runner --edges myedges.tsv \\\n        --output-clusters clusters.json \\\n        --oslom-output oslom-files\n\nAfter execution you will get a JSON formatted file with the clusters found by OSLOM from the provided network edges file.\n\nThis OSLOM Runner supports the following command line options:\n\n* `--edges`: the network edges file in TSV (Tab-separated values) format.\n* `--output-clusters`: the found clusters output file in JSON format.\n* `--oslom-output`: the output directory to put resulting OSLOM files.\n* `--min-cluster-size`: the minimum cluster size for filtering after running OSLOM. Default: `0`.\n* `--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 the [OSLOM documentation](http://www.oslom.org/code/ReadMe.pdf) for more information.\n\nFinally, you can also pass custom OSLOM arguments (with the exception of the `-f` option!) after all options to the runner using the following command:\n\n    oslom-runner --edges myedges.tsv \\\n        --output-clusters clusters.json \\\n        --oslom-output oslom-files \\\n        --oslom-exec /opt/oslom/oslom2_dir \\\n        -- -hr 1 -r 1\n\nPlease note the usage of double dashes (`--`) to separate the runner's own arguments from the OSLOM native ones.\n\nThe 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.\n\nWhen you pass your own OSLOM arguments, none of the default options will be used. You should **NEVER** give the `-f` option because the runner automatically fills the value for it accordingly.\n\n## Using Programatically\n\nThis OSLOM Runner can be used programatically inside your own Python scripts as well.\n\nThere are two main functions to run OSLOM, both using nearly the same arguments:\n\n* `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.\n* `run_in_memory()`: similar to `run()` 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.\n\nThe arguments for these functions must be a `Namespace` object from the `argparse` module. A working example for both functions is below:\n```python\nfrom argparse import Namespace\nimport oslom\n\n# run OSLOM with files already on disk\nargs = Namespace()\nargs.edges = \"/path/to/input_edges.tsv\"\nargs.output_clusters = \"/path/to/output_clusters.json\"\nargs.oslom_output = \"/path/to/oslom_aux_files\"\nargs.min_cluster_size = oslom.DEF_MIN_CLUSTER_SIZE\nargs.oslom_exec = oslom.DEF_OSLOM_EXEC\nargs.oslom_args = oslom.DEF_OSLOM_ARGS\noslom.run(args)\n\n# run OSLOM with data in Python objects\nargs = Namespace()\nargs.min_cluster_size = 0\nargs.oslom_exec = oslom.DEF_OSLOM_EXEC\nargs.oslom_args = oslom.DEF_OSLOM_ARGS\n\n# edges is an iterable of tuples (source, target, weight)\n# in the same format as the command-line version\nedges = [(0, 1, 1.0), (1, 2, 1), (2, 0, 1)]\nclusters = oslom.run_in_memory(args, edges)\nprint(clusters)\n```\n\n## License\n\nThis software is under the **Apache License 2.0**.\n\n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n\n        http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing, software\n    distributed under the License is distributed on an \"AS IS\" BASIS,\n    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n    See the License for the specific language governing permissions and\n    limitations under the License.\n\n\n\n",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "https://github.com/hhromic/python-oslom-runner/tarball/1.5",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/hhromic/python-oslom-runner",
        "keywords": "oslom,runner,clustering,communities",
        "license": "Apache-2.0",
        "maintainer": "Hugo Hromic",
        "maintainer_email": "hhromic@gmail.com",
        "name": "oslom-runner",
        "package_url": "https://pypi.org/project/oslom-runner/",
        "platform": "all",
        "project_url": "https://pypi.org/project/oslom-runner/",
        "project_urls": {
            "Download": "https://github.com/hhromic/python-oslom-runner/tarball/1.5",
            "Homepage": "https://github.com/hhromic/python-oslom-runner"
        },
        "release_url": "https://pypi.org/project/oslom-runner/1.5/",
        "requires_dist": [
            "simplejson"
        ],
        "requires_python": "",
        "summary": "An OSLOM (community finding) runner for Python",
        "version": "1.5"
    },
    "last_serial": 4590074,
    "releases": {
        "1.5": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "704a87d25772d460e4a17659235123ec",
                    "sha256": "a0d021be4c2f72aa4854e86325cd2a3e165dee9f95ec90d6fc6541eaf98f8231"
                },
                "downloads": -1,
                "filename": "oslom_runner-1.5-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "704a87d25772d460e4a17659235123ec",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": null,
                "size": 12117,
                "upload_time": "2018-12-12T12:58:00",
                "url": "https://files.pythonhosted.org/packages/de/57/fab406c161ddef1d3ff4591598d36cebdbbcd0b3c4f5a465e1c017fd6d8a/oslom_runner-1.5-py2.py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "a8b5fa2fe52b2baba4a3be63fc3afeca",
                    "sha256": "fe916b4f28adcd7d54acbcfeec133c514c933e15849521f7a8e2c17c9c333f95"
                },
                "downloads": -1,
                "filename": "oslom-runner-1.5.tar.gz",
                "has_sig": false,
                "md5_digest": "a8b5fa2fe52b2baba4a3be63fc3afeca",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 6857,
                "upload_time": "2018-12-12T12:58:01",
                "url": "https://files.pythonhosted.org/packages/82/18/1f1ec7b397c06f9bee5bfb6d147c92b4f40ab961ca96384ad5b19a6140c1/oslom-runner-1.5.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "704a87d25772d460e4a17659235123ec",
                "sha256": "a0d021be4c2f72aa4854e86325cd2a3e165dee9f95ec90d6fc6541eaf98f8231"
            },
            "downloads": -1,
            "filename": "oslom_runner-1.5-py2.py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "704a87d25772d460e4a17659235123ec",
            "packagetype": "bdist_wheel",
            "python_version": "py2.py3",
            "requires_python": null,
            "size": 12117,
            "upload_time": "2018-12-12T12:58:00",
            "url": "https://files.pythonhosted.org/packages/de/57/fab406c161ddef1d3ff4591598d36cebdbbcd0b3c4f5a465e1c017fd6d8a/oslom_runner-1.5-py2.py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "a8b5fa2fe52b2baba4a3be63fc3afeca",
                "sha256": "fe916b4f28adcd7d54acbcfeec133c514c933e15849521f7a8e2c17c9c333f95"
            },
            "downloads": -1,
            "filename": "oslom-runner-1.5.tar.gz",
            "has_sig": false,
            "md5_digest": "a8b5fa2fe52b2baba4a3be63fc3afeca",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 6857,
            "upload_time": "2018-12-12T12:58:01",
            "url": "https://files.pythonhosted.org/packages/82/18/1f1ec7b397c06f9bee5bfb6d147c92b4f40ab961ca96384ad5b19a6140c1/oslom-runner-1.5.tar.gz"
        }
    ]
}