{ "info": { "author": "Philipp Wiesner", "author_email": "mail@philippwiesner.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "Environment :: Console", "Environment :: Web Environment", "Intended Audience :: Education", "Intended Audience :: Science/Research", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", "Programming Language :: JavaScript", "Programming Language :: Python", "Programming Language :: Python :: 2", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.4", "Programming Language :: Python :: 3.5", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7", "Topic :: Education", "Topic :: Scientific/Engineering :: Visualization" ], "description": "# RFVis [![PyPI version fury.io](https://badge.fury.io/py/rfvis.svg)](https://pypi.org/project/rfvis/) [![Supported versions](https://img.shields.io/pypi/pyversions/rfvis.svg)](https://pypi.org/project/rfvis/) [![License](https://img.shields.io/pypi/l/rfvis.svg)](https://pypi.org/project/rfvis/)\n\nA tool for visualizing the structure and performance of Random Forests (and other ensemble methods based on decision trees).\n\n![Tree](images/tree.png)\n\nRFVis offers a [Command Line API](#command-line-api) and a [Python API](#python-api) which works on a [sklearn.ensemble.RandomForestClassifier](https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.RandomForestClassifier.html).\n\n\n## Getting Started \n\nInstall and update RFVis via [pip](https://pip.pypa.io/en/stable/quickstart/):\n\n```\n$ pip install rfvis\n```\n\nThis will allow you interactively visualize a fitted Random Forest (RF) in your\nbrowser. To directly generate SVG files from your model you also need to install\n[Node.js](https://nodejs.org/en/download/), see [Command Line Interface](#command-line-interface) for more information.\n\n\n## Command Line API\n\nRFVis offers a command line tool to either generate SVG files directly from\nyour input data (`rfvis cli `) or to spin up a web-based GUI for a more\ninteractive analysis (`rfvis gui `).\n\nTo see all available commands run:\n```\n$ rfvis --help\nUsage: rfvis [OPTIONS] COMMAND [ARGS]...\n\n A tool for visualizing the structure and performance of Random Forests\n\nOptions:\n --version Show the version and exit.\n --help Show this message and exit.\n\nCommands:\n cli Command line interface to generate SVGs.\n gui Web-based graphical user interface.\n```\n\n\n### Graphical User Interface\n\nTo interactively analyze your forest with the web-based GUI run:\n```\n$ rfvis gui /path/to/data\n * Running on http://127.0.0.1:8080/ (Press CTRL+C to quit)\n```\nYou can now open up your browser at to see something like this:\n\n![Tree](images/screenshot.png)\n\n\n### Command Line Interface\n\nTo use the Command Line Interface (CLI) you need to have\n[Node.js](https://nodejs.org/en/download/) v8+ installed on your system. This\nis a technical limitation due to the fact that the rendering is written in\nJavascript. You do not need to install any other package though, the CLI\nintegrates into the command line tool you already installed via pip:\n```\n$ rfvis cli /path/to/data\n>> Exported \"/dev/random-forest-visualization/tree-0.svg\"\n>> Exported \"/dev/random-forest-visualization/tree-1.svg\"\n>> Exported \"/dev/random-forest-visualization/tree-2.svg\"\n>> Exported \"/dev/random-forest-visualization/tree-3.svg\"\n...\n```\n\nGet a full list of available options with `--help`:\n```\n$ rfvis cli --help\nUsage: rfvis cli [OPTIONS] FOREST_JSON\n\n Web-based graphical user interface.\n\n As Python is unable to render React components, we make a subprocess call to a small\n Node.js application which will do the rendering and also store the created SVG\n files. This command requires that Node.js is installed on your system!\n\n FOREST_JSON: Path to the JSON file that contains the forest's data.\n\nOptions:\n -o, --out PATH Output path of the SVG files. [default: (current\n working directory)]\n -w, --width INTEGER Width of the SVG. [default: 800]\n -h, --height INTEGER Height of the SVG. [default: 800]\n --trunk-length INTEGER Length of the trunk which influences the overall tree\n size. [default: 100]\n --display-depth INTEGER Maximum depth of the tree rendering. Cut of leaves are\n visualized as pie chart consolidation nodes.\n --branch-color [Impurity] Coloring of the branches. [default: Impurity]\n --leaf-color [Impurity|Best Class]\n Coloring of the leaves. [default: Impurity]\n --help Show this message and exit.\n```\n\n\n### Input Data\n\nThe data for the Command Line API must be available on your filesystem as a JSON file\nfor the forest and additionally one CSV file per tree. Both data formats will\nbe extended with properties in the future, this is just the minimal set.\n\nYou can find a working example under `examples/PolSAR`.\n\n\n#### Forest JSON\n\nThe main `forest.json` holds all information about the ensemble model:\n\n- **name** (string): Name of your forest, will be displayed in the GUI\n- **error** (float): The error (e.g. the out-of-bag or validation error) of the \n entire ensemble model, will be displayed in the GUI\n- **n_samples** (int): Number of samples the model was trained on\n- **correlationMatrix** (float[][]): Correlation between the single trees within\n the model. Has dimensions `NxN` where `N` is the number of trees.\n This will be used to compute the forest map. \n- **classes**: The output classes\n - **name** (string): Name of the class\n - **color** (int, int, int): RGB values in the range of 0-255 which\n determine the color of the class in the visualization\n- **trees**: The trees in the forest\n - **error** (float): The error (again could be either the out-of-bag or\n validation error) of the single tree\n - **data** (string): Relative path to the CSV file containing the tree data\n\n\n#### Tree CSV\n\nFor each tree specified in the `forest.json` RFVis expects a CSV file where one\nentry represents one node in the tree. An entry has the following format:\n\n- **id** (int): ID of the node\n- **depth** (int) Depth of the node in the tree (starting at `0`)\n- **n_node_samples** (int): Number of training samples reaching the node\n- **impurity** (float): Impurity of the node (`0`-`1`)\n- **value** (int[]): Class distribution within the node, i.e. every entry \n represents the amount of samples within the node that respond to a specific \n class. The index corresponds to the indices in `forest.classes`.\n\n\n## Python API\n\nRFVis also offers a Python API which works directly on a scikit-learn RandomForestClassifier.\nYou can find a working example under `examples/scikit_learn.py`.\n\nThe function `rfvis.gui()` visualizes a fitted RandomForestClassifier in a web based graphical user interface.\nThe server runs in a separate process and is available at `http://localhost:`.\n\n```python\ngui(model, data=None, target=None, name=None, class_names=None, class_colors=None, port=8080)\n```\n\nArgs:\n\n- **model** ([sklearn.ensemble.RandomForestClassifier](https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.RandomForestClassifier.html)):\n The model to visualize.\n- **data** (array-like, shape=(n_samples, n_features)): The training input samples that were used to fit the model.\n Used to compute the out-of-bag error and correlation of the individual trees.\n If not provided, the forest view will have no significance.\n- **target** (array-like, shape=n_samples): The target values (class labels) that were used to fit the model.\n Used to compute the out-of-bag error and correlation of the individual trees.\n If not provided, the forest view will have no significance.\n- **name** (str): Optional name of the model which will be displayed in the frontend.\n- **class_names** (List[str]): Optional list of names of the target classes\n- **class_colors** (List[str]): Optional list of browser interpretable colors for the target classes.\n See https://developer.mozilla.org/en-US/docs/Web/CSS/color_value.\n- **port** (int): Port on which the frontend will run on. Defaults to 8080.\n\nReturns:\n- **process** (multiprocessing.Process): Subprocess that runs the server. Can be terminated with\n [process.terminate()](https://docs.python.org/3/library/multiprocessing.html#multiprocessing.Process.terminate).\n\n## Development\n\nThe repository contains a `Pipfile` for conveniently creating a virtualenv\nfor development. Just install [pipenv](https://pipenv.readthedocs.io/en/latest/)\nand run:\n\n```\n$ pipenv install\n```\n\nYou can now e.g. start the server on the default port 8080 via:\n\n```\n$ pipenv run rfvis gui \n```\n\nNote that you need to build the frontend bundle first before you can\nactually see the application working on `http://localhost:8080`.\n\nTo build the frontend you need Node.js installed. First install all \ndev-dependencies by running the following \nfrom within the `./rfvis/client` directory:\n\n```\n$ npm install\n```\n\nNow you can build a production-ready bundle via:\n\n```\n$ npm run build\n```\n\nIf you have the Python server running you should now be able to see the\napplication at `http://localhost:8080`.\n\nFor developing on the frontend more conveniently run:\n\n```\n$ npm start\n```\n\nTo start a development server with hot reloading at `http://localhost:3000`.", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/birnbaum/rfvis", "keywords": "random-forest,visualization,decision-trees,d3js,react", "license": "MIT", "maintainer": "", "maintainer_email": "", "name": "rfvis", "package_url": "https://pypi.org/project/rfvis/", "platform": "", "project_url": "https://pypi.org/project/rfvis/", "project_urls": { "Bug Tracker": "https://github.com/birnbaum/rfvis/issues", "Homepage": "https://github.com/birnbaum/rfvis" }, "release_url": "https://pypi.org/project/rfvis/0.3.0/", "requires_dist": null, "requires_python": "", "summary": "A tool for visualizing the structure and performance of Random Forests", "version": "0.3.0" }, "last_serial": 4639218, "releases": { "0.2.0": [ { "comment_text": "", "digests": { "md5": "98e2b96473e35d4f4e83b87586393f75", "sha256": "bdf5115880420d774c0ab308c699c0adbe7f84f8892f354904f77d3bc6518207" }, "downloads": -1, "filename": "rfvis-0.2.0.tar.gz", "has_sig": false, "md5_digest": "98e2b96473e35d4f4e83b87586393f75", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 3257908, "upload_time": "2018-12-11T07:14:22", "url": "https://files.pythonhosted.org/packages/8e/f6/50300ca2542f23a42c304a315c32d018d456838a5912441c6bb791bfdd4c/rfvis-0.2.0.tar.gz" } ], "0.2.1": [ { "comment_text": "", "digests": { "md5": "be91ef8f618e2254051673bb2ba215f9", "sha256": "3e2aec0bfede864bd4924a33205e69a7ed2f37bba53e926de46bbe6c9d58993e" }, "downloads": -1, "filename": "rfvis-0.2.1.tar.gz", "has_sig": false, "md5_digest": "be91ef8f618e2254051673bb2ba215f9", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 2342888, "upload_time": "2018-12-12T23:30:40", "url": "https://files.pythonhosted.org/packages/60/73/252a95df19392f27bc0bcc2a1793b44a0513afd1970d7695b66788cad1f2/rfvis-0.2.1.tar.gz" } ], "0.2.1a1": [ { "comment_text": "", "digests": { "md5": "c8e1cd776fd01946a6e6b8bb0e46be07", "sha256": "07c966d6ab6e25bdb85f05d1e213605945e9cbb3ef6c19a10bc6891a4304cdcd" }, "downloads": -1, "filename": "rfvis-0.2.1a1.tar.gz", "has_sig": false, "md5_digest": "c8e1cd776fd01946a6e6b8bb0e46be07", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 3259213, "upload_time": "2018-12-12T12:18:31", "url": "https://files.pythonhosted.org/packages/bd/70/b72d5b5c345f22d56475904cfca2dae9d6ce8ade8b3ced711d6728989f39/rfvis-0.2.1a1.tar.gz" } ], "0.3.0": [ { "comment_text": "", "digests": { "md5": "c66c07f03e7c35206825f06d4cb77609", "sha256": "58fad151e5d6e8b5e0df9b719a485e9e4f7399dbc7da0f9e113064e09524f183" }, "downloads": -1, "filename": "rfvis-0.3.0.tar.gz", "has_sig": false, "md5_digest": "c66c07f03e7c35206825f06d4cb77609", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 2077481, "upload_time": "2018-12-27T22:57:37", "url": "https://files.pythonhosted.org/packages/f6/f7/9506f3442bf5946a6381b79304be8426845057ee26a66616c86330e0c45b/rfvis-0.3.0.tar.gz" } ], "0.3.0a1": [ { "comment_text": "", "digests": { "md5": "65d779d9e22de07f5ac59cfeccadfc03", "sha256": "b2f2af5e95a3b90918dee0e14ad5251ce4abbf2852849f3382cf823dd64e57b2" }, "downloads": -1, "filename": "rfvis-0.3.0a1.tar.gz", "has_sig": false, "md5_digest": "65d779d9e22de07f5ac59cfeccadfc03", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 2077564, "upload_time": "2018-12-27T22:35:29", "url": "https://files.pythonhosted.org/packages/12/60/4c09083868e6f4370c607d1e826a361ec1d21dfae0c7a046d7df3d3fc5ff/rfvis-0.3.0a1.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "c66c07f03e7c35206825f06d4cb77609", "sha256": "58fad151e5d6e8b5e0df9b719a485e9e4f7399dbc7da0f9e113064e09524f183" }, "downloads": -1, "filename": "rfvis-0.3.0.tar.gz", "has_sig": false, "md5_digest": "c66c07f03e7c35206825f06d4cb77609", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 2077481, "upload_time": "2018-12-27T22:57:37", "url": "https://files.pythonhosted.org/packages/f6/f7/9506f3442bf5946a6381b79304be8426845057ee26a66616c86330e0c45b/rfvis-0.3.0.tar.gz" } ] }