{
    "info": {
        "author": "Wesley Tansey",
        "author_email": "tansey@cs.utexas.edu",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 3 - Alpha",
            "Intended Audience :: Science/Research",
            "License :: OSI Approved :: MIT License",
            "Programming Language :: Python :: 2",
            "Programming Language :: Python :: 2.7",
            "Topic :: Scientific/Engineering"
        ],
        "description": "Vector-Space Markov Random Fields (VS-MRFs)\n============================================\n\n![Example of a learned VS-MRF](https://raw.githubusercontent.com/tansey/vsmrfs/master/data/mfp_top.png)\n\nThis package provides support for learning MRFs where each node-conditional can be any generic exponential family distribution. Currently supported node-conditionals are Bernoulli, Gamma, Gaussian, Dirichlet, and Point-Inflated models. See `exponential_families.py` for guidance on how to add a custom node-conditional distribution.\n\nInstallation\n------------\n\n`pip install vsmrfs`\n\nRequires `numpy`, `scipy`, and `matplotlib`.\n\nRunning\n-------\n\n### 0) Experiment directory structure\n\nThe `vsmrfs` package is very opinionated. It assumes you have an experiment directory with a very specific structure. If your experiment directory is `exp`, then you need the following structure:\n\n```\nexp/\n    args/\n    data/\n        nodes.csv\n        sufficient_statistics.csv\n    edges/\n    metrics/\n    plots/\n    weights/\n```\n\nNote that all you really need at first is the `exp/data/` structure and the two files. If you generate your data from the synthetic dataset creator, the structure will be created for you.\n\n### 1a) Generating synthetic data (optional)\n\nIf you are just trying to run the package or conduct some benchmarks on the algorithm, you can create a synthetic dataset which will setup all of the experiment structure for you. For example, say you wanted to run an experiment with two Bernoulli nodes and a three-dimensional Dirichlet node, and you want to use `foo/` as your experiment directory:\n\n`vsmrf-gen foo --nodes b b d3`\n\nThis will generate a `foo` directory and all of the structure from step 0, using some default parameters for sparsity and sample sizes. You can see the full list of options with `vsmrf-gen --help`.\n\n### 1b) Preparing your data (alternative to 1a)\n\nIf you actually have some data that you're trying to model, you need to get it into the right format. Assuming you know your data types, and your experiment directory is `foo`, you need to generate two files:\n\n`foo/data/nodes.csv`: This is a single-line CSV file containing the data-types of all your node-conditionals. Currently supported options:\n\n- `b`: Bernoulli node\n- `n`: Normal or Gaussian node\n- `g`: Gamma node\n- `d#`: Dirichlet node, where # is replaced with the dimensionality of the Dirichlet, e.g. `d3` for a 3-parameter Dirichlet\n- `ziX`: Zero-inflated or generic point-inflated node, where `X` is replaced by the inflated distribution. This is a recursive definition, so you can have multiple inflated points, e.g., `zizig` would be a two-point inflated Gamma distribution.\n\n`foo/data/sufficient_statistics.csv`: A CSV matrix of sufficient statistics for all of the node-conditionals. The first line should be the column-to-node-ID mapping. So for example if you have a dataset of two Bernoulli nodes and a 3-dimensional Dirichlet, your header would look like `0,1,2,2,2` since `node0` and `node1` are both Bernoulli (i.e. univariate sufficient statistics) and `node2` is your Dirichlet, with 3 sufficient statistics. Every subsequent row in the file then corresponds to a data sample.\n\n### 2) MLE via Pseudo-likelihood\n\nTo learn a VS-MRF, we make a pseudo-likelihood approximation that effectively decouples all the nodes. This makes the problem convex and separable, enabling us to learn each node independently. If you have access to a cluster or distributed compute environment, this makes the process very fast since you can learn each node on a different machine, then stitch the whole graph back together in step 3.\n\nSay you want to learn the Dirichlet node from step 2, using a solution path approach so you can avoid hyperparameter setting:\n\n`vsmrf-learn foo --target 2 --solution_path`\n\nThis will load the data from the `foo` experiment directory and learn the pseudo-edges for `node2`, which is our Dirichlet node. You can see the full list of options with `vsmrf-learn --help`.\n\n### 3) Stitching the MRF together\n\nOnce all the nodes have been learned, the pseudo-edges need to be combined back together to form a single graph. Since we are learning approximate models, there will be times when a pseudo-edge for `nodeA-nodeB` exists but `nodeB-nodeA` does not. In that case, we have to decide whether to include the edge in the final graph or not; that is, should we `OR` the edges together or `AND` them? The package will create both, but empirically it seems performance is slightly better with the `AND` graph.\n\nContinuing our example, to stitch together our three node MRF:\n\n`vsmrf-stitch foo --nodes b b d3`\n\nIf you generated your data synthetically, such that you know the ground truth of the model, you can evaluate the resulting graph:\n\n`vsmrf-stitch foo --nodes b b d3 --evaluate`\n\nSee `vsmrf-stitch --help` for a full list of options.\n\nReference\n---------\n```\n@inproceedings{tansey:etal:2015,\n  title={Vector-Space Markov Random Fields via Exponential Families},\n  author={Tansey, Wesley and Madrid-Padilla, Oscar H and Suggala, Arun and Ravikumar, Pradeep},\n  booktitle={Proceedings of the 32nd International Conference on Machine Learning (ICML-15)},\n  year={2015}\n}\n```",
        "description_content_type": null,
        "docs_url": null,
        "download_url": null,
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/tansey/vsmrfs",
        "keywords": "statistics biostatistics fdr hypothesis machinelearning",
        "license": "MIT",
        "maintainer": null,
        "maintainer_email": null,
        "name": "vsmrfs",
        "package_url": "https://pypi.org/project/vsmrfs/",
        "platform": "UNKNOWN",
        "project_url": "https://pypi.org/project/vsmrfs/",
        "project_urls": {
            "Homepage": "https://github.com/tansey/vsmrfs"
        },
        "release_url": "https://pypi.org/project/vsmrfs/0.9.0/",
        "requires_dist": null,
        "requires_python": null,
        "summary": "Vector-Space Markov Random Fields",
        "version": "0.9.0"
    },
    "last_serial": 1546032,
    "releases": {
        "0.9.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "7187546b2fb70129a67ec09b7138e8fa",
                    "sha256": "eb5214fcbc879fa032f3568c56592cdb25e2e69ab8ed086430fce6749b3d7f0b"
                },
                "downloads": -1,
                "filename": "vsmrfs-0.9.0-cp27-none-macosx_10_9_x86_64.whl",
                "has_sig": false,
                "md5_digest": "7187546b2fb70129a67ec09b7138e8fa",
                "packagetype": "bdist_wheel",
                "python_version": "cp27",
                "requires_python": null,
                "size": 6883,
                "upload_time": "2015-05-13T19:50:37",
                "url": "https://files.pythonhosted.org/packages/5f/82/d2fa222730bdcdea98e73ff0dd19f58e20cc0d3e5ef798ea51916235ed1d/vsmrfs-0.9.0-cp27-none-macosx_10_9_x86_64.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "8669b7cee6a5b884f6ea117d5d8f9c7f",
                    "sha256": "96bd461ba3b8d2d7b0312c2de3fc1a14084ae15fb1eb83750cfea5ab8d887cb4"
                },
                "downloads": -1,
                "filename": "vsmrfs-0.9.0.tar.gz",
                "has_sig": false,
                "md5_digest": "8669b7cee6a5b884f6ea117d5d8f9c7f",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 4018,
                "upload_time": "2015-05-13T19:50:40",
                "url": "https://files.pythonhosted.org/packages/30/36/a6c4f77e801fc14e0eb40eb4c37231aebc0791e492e18a48d767562d736f/vsmrfs-0.9.0.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "7187546b2fb70129a67ec09b7138e8fa",
                "sha256": "eb5214fcbc879fa032f3568c56592cdb25e2e69ab8ed086430fce6749b3d7f0b"
            },
            "downloads": -1,
            "filename": "vsmrfs-0.9.0-cp27-none-macosx_10_9_x86_64.whl",
            "has_sig": false,
            "md5_digest": "7187546b2fb70129a67ec09b7138e8fa",
            "packagetype": "bdist_wheel",
            "python_version": "cp27",
            "requires_python": null,
            "size": 6883,
            "upload_time": "2015-05-13T19:50:37",
            "url": "https://files.pythonhosted.org/packages/5f/82/d2fa222730bdcdea98e73ff0dd19f58e20cc0d3e5ef798ea51916235ed1d/vsmrfs-0.9.0-cp27-none-macosx_10_9_x86_64.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "8669b7cee6a5b884f6ea117d5d8f9c7f",
                "sha256": "96bd461ba3b8d2d7b0312c2de3fc1a14084ae15fb1eb83750cfea5ab8d887cb4"
            },
            "downloads": -1,
            "filename": "vsmrfs-0.9.0.tar.gz",
            "has_sig": false,
            "md5_digest": "8669b7cee6a5b884f6ea117d5d8f9c7f",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 4018,
            "upload_time": "2015-05-13T19:50:40",
            "url": "https://files.pythonhosted.org/packages/30/36/a6c4f77e801fc14e0eb40eb4c37231aebc0791e492e18a48d767562d736f/vsmrfs-0.9.0.tar.gz"
        }
    ]
}