{
    "info": {
        "author": "Francis C. Motta",
        "author_email": "fmotta@fau.edu",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 4 - Beta"
        ],
        "description": "# Persistence Images: A Stable Vector Representation of Persistent Homology\n## Description\nThis module defines the Python class PersistenceImager used to vectorize persistence diagrams into persistence images (see [PI] http://www.jmlr.org/papers/volume18/16-337/16-337.pdf for details).\n\n## Dependencies\n* Interpreter\n```\nPython 3.6.0\n```\n\n* Modules\n```\nnumpy 1.11.3\nmatplotlib 2.0.0\n```\n\n## Installation\n\nYou can install the latest version of the PersistenceImages module using `pip`:\n```\n$ pip install PersistenceImages\n```\nOnce installed, you may access the PersistenceImages module and methods therein:\n```\n>>> import PersistenceImages.persistence_images as pimg\n```\n## PersistenceImager()\nThe PersistenceImager() class is the workhorse of the PersistenceImages package and is used to transform a diagram. An instantiation of a PersistenceImager() object must first be created, and will contain the attributes which define the persistence image hyperparameters:\n* **birth_range**: tuple specifying the left and right image boundaries\n* **pers_range**: tuple specifying the lower and upper image boundaries\n* **pixel_size**: a float specifying the width and height of each image pixels\n* **weight**: weight function that scales the contribution of each persistence pair to the final image \n* **weight_params**: arguments needed to specify the weight function\n* **kernel**: cumulative distribution function of the kernel which replaces each persistence pair\n* **kernel_params**: arguments needed to specify the kernel CDF\n\nCurrently, only the CDF of a general bivariate normal distribution is implemented in `cdfs.py`.  The shape of this distribution is controlled by the parameter 'sigma' which is expected to be a valid 2x2, positive-definite covariance matrix. \n\n**NOTE**: For mathematical reasons, a standard isotropic bivariate normal i.e. $`\\Sigma=[[\\sigma, 0],[0, \\sigma]]`$, will be *much* faster to compute than a non-isotropic distribution kernel. \n\n## Example\nFirst instantiate a PersistenceImager() object:\n```\n>>> pers_imager = pimg.PersistenceImager()\n```\nPrinting a PersistenceImager() object will print its hyperparameters (defaults in this case):\n```\n>>> print(pers_imager)\n\nPersistenceImager object:\n  pixel size: 0.2\n  resolution: (5, 5)\n  birth range: (0, 1)\n  persistence range: (0, 1)\n  weight: linear_ramp\n  kernel: bvncdf\n  weight parameters: {}\n  kernel parameters: {sigma: [[ 1.  0.]\n                              [ 0.  1.]]}\n```\nThe `transform()` method can then be called on a (N,2) numpy array to generate a persistence image from the input diagram:\n```\n>>> import numpy as np\n>>> pers_dgm = np.array([[0.5, 0.8], [0.7, 1.2], [2.5, 4.0]])\n>>> pers_img = pers_imager.transform(pers_dgm, skew=True)\n\narray([[0.00430663, 0.00453225, 0.0045929 , 0.00448349, 0.00421781],\n       [0.00474815, 0.00501502, 0.00510404, 0.00500795, 0.00473973],\n       [0.005063  , 0.00537381, 0.00550102, 0.00543453, 0.00518493],\n       [0.00523385, 0.00559182, 0.00576862, 0.00575055, 0.005544  ],\n       [0.00526161, 0.00567059, 0.00590921, 0.00595932, 0.00582126]])\n```\nThe option `skew=True` specifies that the diagram is currently in birth-death coordinates and must be first transformed to birth-persistence coordinates. \n\nThe `plot_diagram()` and `plot_image()` methods can be used to generate plots of a diagram and the corresponding image:\n\n```\n>>> pers_imager.plot_diagram(pers_dgm, skew=True)\n>>> pers_imager.plot_image(pers_dgm, skew=True)\n```\nA finer resolution image is made by decreasing the `pixel_size` attribute:\n```\n>>> pers_imager.pixel_size = 0.02\n>>>\t\n\nPersistenceImager object:\n  pixel size: 0.02      <----\n  resolution: (50, 50)  <----\n  birth range: (0, 1)\n  persistence range: (0, 1)\n  weight: linear_ramp\n  kernel: bvncdf\n  weight parameters: {}\n  kernel parameters: {sigma: [[ 1.  0.]\n                              [ 0.  1.]]}\n```\nUpdating attributes of a PersistenceImager() object will automatically update other dependent image attributes: \n```\n>>> pers_imager.birth_range = (0, 2)\n>>> print(pers_imager)\n\nPersistenceImager object: \n  pixel size: 0.02 \n  resolution: (100, 50)   <---\n  birth range: (0, 2)     <---\n  persistence range: (0, 1) \n  weight: linear_ramp \n  kernel: bvncdf \n  weight parameters: {} \n  kernel parameters: {sigma: [[1.  0.]\n\t\t\t\t\t\t\t  [0.  1.]]}\n```\nOther weighting functions can also be used and are implemented in in the `PersistenceImages.weighting_fxns` modules. Here we weight pairs by their persistence squared:\n```\n>>> pers_imager.weight = pimg.weighting_fxns.persistence\n>>> pers_imager.weight_params = {'n': 2}\n```\nThe PersistenceImager() class implements `.fit()` and `.fit_transform()` methods that take an iterable collection of persistence diagrams as input. Currently these methods simply set the birth and persistence ranges according to the minimum and maximum birth and persistence values of all pairs across the collection of diagrams.\n```\n>>> pers_imager.fit([np.array([[0.5, 0.8], [0.7, 1.2], [2.5, 4.0]]), np.array([[1.2, 2.1], [0.7, 0.9], [1.1, 4.3]])])\n>>> print(pers_imager)\n\nPersistenceImager object: \n  pixel size: 0.02 \n  resolution: (100, 150)         <---\n  birth range: (0.5, 2.5)        <---\n  persistence range: (0.2, 3.2)  <---\n  weight: persistence \n  kernel: bvncdf \n  weight parameters: {n: 2} \n  kernel parameters: {sigma: [[1.  0.]\n\t\t\t\t\t\t\t  [0.  1.]]}\n```\nTo adjust the bandwidth of the Gaussian kernels centered on each persistence pair we change the variances of the 'sigma' parameter of the `bvncdf` (bi-variate normal) kernel.  To use a standard isotropic normal we can also just specify the variances by a single number.\n```\n>>> pers_imager.kernel_params = {'sigma': np.array([[.01, 0],[0, .01]])}\n>>> # or pers_imager.kernel_params = {'sigma': .01}\n```\n\n## License\nThis project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.",
        "description_content_type": "",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://gitlab.com/csu-tda/PersistenceImages",
        "keywords": "persistence diagrams,persistent homology,persistence images,computational topology,topological data analysis",
        "license": "MIT",
        "maintainer": "",
        "maintainer_email": "",
        "name": "PersistenceImages",
        "package_url": "https://pypi.org/project/PersistenceImages/",
        "platform": "",
        "project_url": "https://pypi.org/project/PersistenceImages/",
        "project_urls": {
            "Homepage": "https://gitlab.com/csu-tda/PersistenceImages"
        },
        "release_url": "https://pypi.org/project/PersistenceImages/1.3.3/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Functions to vectorize persistence diagrams into persistence images (see [PI] http://www.jmlr.org/papers/volume18/16-337/16-337.pdf for details)",
        "version": "1.3.3"
    },
    "last_serial": 4642365,
    "releases": {
        "1.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "7a1ff497b6e8ec091bf9151cb403e268",
                    "sha256": "3c1338944265d68f1a4637099d945c091f22bc6143f36af8fa592b96aabffcf0"
                },
                "downloads": -1,
                "filename": "PersistenceImages-1.1.tar.gz",
                "has_sig": false,
                "md5_digest": "7a1ff497b6e8ec091bf9151cb403e268",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 8706,
                "upload_time": "2018-12-17T17:30:11",
                "url": "https://files.pythonhosted.org/packages/41/12/2310a0d42d1181e6a0528e4299f1bb72e71dbe9b1437edbce309d366305e/PersistenceImages-1.1.tar.gz"
            }
        ],
        "1.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "8a026b4ef36118e3767b651032cf172d",
                    "sha256": "1d7c0298f72c87ca2563a1c35c8cf68f9c2f762680efa8571836191c7fd3e131"
                },
                "downloads": -1,
                "filename": "PersistenceImages-1.2.tar.gz",
                "has_sig": false,
                "md5_digest": "8a026b4ef36118e3767b651032cf172d",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 8849,
                "upload_time": "2018-12-17T17:55:24",
                "url": "https://files.pythonhosted.org/packages/05/7d/06600a413a77c2437754d503953fa5aef12a6b8ee98bf1eb7dd5e1eb5cc2/PersistenceImages-1.2.tar.gz"
            }
        ],
        "1.3": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "8f16a1fc106bd39f53f6dfd0cf4c826b",
                    "sha256": "f3f4edc83d07e59da6d1dd8c6c1b1e6282a13d9dbc201bec5136003cd87b0e4d"
                },
                "downloads": -1,
                "filename": "PersistenceImages-1.3.tar.gz",
                "has_sig": false,
                "md5_digest": "8f16a1fc106bd39f53f6dfd0cf4c826b",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 9155,
                "upload_time": "2018-12-18T14:57:25",
                "url": "https://files.pythonhosted.org/packages/6b/c9/848f7a08144cefae0b8edb1fed0cd4e3e8f2bc9722af13cf2c8205929e46/PersistenceImages-1.3.tar.gz"
            }
        ],
        "1.3.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "2ffbec93eae07bbff05913b03075889d",
                    "sha256": "b6af1d446047e3f5d8f3139cd111932bce77f584b7cac9316f114e96cfc0c5d3"
                },
                "downloads": -1,
                "filename": "PersistenceImages-1.3.1.tar.gz",
                "has_sig": false,
                "md5_digest": "2ffbec93eae07bbff05913b03075889d",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 9219,
                "upload_time": "2018-12-18T17:49:10",
                "url": "https://files.pythonhosted.org/packages/2e/d8/7abe8f37631e76545172783f602dae111d78d095f3c7ecc0b212da211b2f/PersistenceImages-1.3.1.tar.gz"
            }
        ],
        "1.3.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "1fb099e84dcc32dd554733e9d8023ea9",
                    "sha256": "961aaf6c566d2f5b96a2f1195f4ca4ae65011c481239c999cf619812ef9180af"
                },
                "downloads": -1,
                "filename": "PersistenceImages-1.3.2.tar.gz",
                "has_sig": false,
                "md5_digest": "1fb099e84dcc32dd554733e9d8023ea9",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 9267,
                "upload_time": "2018-12-18T17:59:21",
                "url": "https://files.pythonhosted.org/packages/2e/00/3fea47efd6b6b270cbfe4ecab6c1eaaab583c521e3207c805ffc663b65a1/PersistenceImages-1.3.2.tar.gz"
            }
        ],
        "1.3.3": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "698cf298d331654155ad5306f5bedd91",
                    "sha256": "9eeca4ccb755479e9312b9d9085e32161e163b55b891d69b1da89ff302ddf172"
                },
                "downloads": -1,
                "filename": "PersistenceImages-1.3.3.tar.gz",
                "has_sig": false,
                "md5_digest": "698cf298d331654155ad5306f5bedd91",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 9263,
                "upload_time": "2018-12-28T21:04:50",
                "url": "https://files.pythonhosted.org/packages/f0/7d/6c07d459dfd70b783e148052232fa7dc65a30df6bb5d354eeb8a94171af2/PersistenceImages-1.3.3.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "698cf298d331654155ad5306f5bedd91",
                "sha256": "9eeca4ccb755479e9312b9d9085e32161e163b55b891d69b1da89ff302ddf172"
            },
            "downloads": -1,
            "filename": "PersistenceImages-1.3.3.tar.gz",
            "has_sig": false,
            "md5_digest": "698cf298d331654155ad5306f5bedd91",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 9263,
            "upload_time": "2018-12-28T21:04:50",
            "url": "https://files.pythonhosted.org/packages/f0/7d/6c07d459dfd70b783e148052232fa7dc65a30df6bb5d354eeb8a94171af2/PersistenceImages-1.3.3.tar.gz"
        }
    ]
}