{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The von Mises-Fisher distribution is a directional distribution on the surface of the unit hypersphere. The probability density function of a unit vector " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\mathbf{x}" }, { "__type": "Text", "__tag": 4046, "value": " is" } ] }, { "__type": "Math", "__tag": 4058, "value": "f(\\mathbf{x}) = \\frac{\\kappa^{d/2-1}}{(2\\pi)^{d/2}I_{d/2-1}(\\kappa)}\n \\exp\\left(\\kappa \\mathbf{\\mu}^T\\mathbf{x}\\right)," }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "where " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\mathbf{\\mu}" }, { "__type": "Text", "__tag": 4046, "value": " is the mean direction, " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\kappa" }, { "__type": "Text", "__tag": 4046, "value": " the concentration parameter, " }, { "__type": "InlineMath", "__tag": 4057, "value": "d" }, { "__type": "Text", "__tag": 4046, "value": " the dimension and " }, { "__type": "InlineMath", "__tag": 4057, "value": "I" }, { "__type": "Text", "__tag": 4046, "value": " the modified Bessel function of the first kind. As " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\mu" }, { "__type": "Text", "__tag": 4046, "value": " represents a direction, it must be a unit vector or in other words, a point on the hypersphere: " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\mathbf{\\mu}\\in S^{d-1}" }, { "__type": "Text", "__tag": 4046, "value": ". " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\kappa" }, { "__type": "Text", "__tag": 4046, "value": " is a concentration parameter, which means that it must be positive (" }, { "__type": "InlineMath", "__tag": 4057, "value": "\\kappa>0" }, { "__type": "Text", "__tag": 4046, "value": ") and that the distribution becomes more narrow with increasing " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\kappa" }, { "__type": "Text", "__tag": 4046, "value": ". In that sense, the reciprocal value " }, { "__type": "InlineMath", "__tag": 4057, "value": "1/\\kappa" }, { "__type": "Text", "__tag": 4046, "value": " resembles the variance parameter of the normal distribution." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The von Mises-Fisher distribution often serves as an analogue of the normal distribution on the sphere. Intuitively, for unit vectors, a useful distance measure is given by the angle " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\alpha" }, { "__type": "Text", "__tag": 4046, "value": " between them. This is exactly what the scalar product " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\mathbf{\\mu}^T\\mathbf{x}=\\cos(\\alpha)" }, { "__type": "Text", "__tag": 4046, "value": " in the von Mises-Fisher probability density function describes: the angle between the mean direction " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\mathbf{\\mu}" }, { "__type": "Text", "__tag": 4046, "value": " and the vector " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\mathbf{x}" }, { "__type": "Text", "__tag": 4046, "value": ". The larger the angle between them, the smaller the probability to observe " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\mathbf{x}" }, { "__type": "Text", "__tag": 4046, "value": " for this particular mean direction " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\mathbf{\\mu}" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In dimensions 2 and 3, specialized algorithms are used for fast sampling " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "3" }, { "__type": "Text", "__tag": 4046, "value": ". For dimensions of 4 or higher the rejection sampling algorithm described in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "4" }, { "__type": "Text", "__tag": 4046, "value": " is utilized. This implementation is partially based on the geomstats package " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "5" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "6" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 1.11" } ] } ] } ], "title": [], "level": 0, "target": null }, "Warns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Raises": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Yields": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Methods": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "pdf(x, mu=None, kappa=1)", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Probability density function." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "logpdf(x, mu=None, kappa=1)", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Log of the probability density function." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "rvs(mu=None, kappa=1, size=1, random_state=None)", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Draw random samples from a von Mises-Fisher distribution." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "entropy(mu=None, kappa=1)", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Compute the differential entropy of the von Mises-Fisher distribution." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "fit(data)", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Fit a von Mises-Fisher distribution to data." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Returns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A von Mises-Fisher variable." } ] } ], "title": [], "level": 0, "target": null }, "Receives": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Warnings": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Attributes": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Parameters": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "mu", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Mean direction of the distribution. Must be a one-dimensional unit vector of norm 1." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "kappa", "annotation": "float", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Concentration parameter. Must be positive." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "seed", "annotation": "{None, int, np.random.RandomState, np.random.Generator}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Used for drawing random variates. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "seed" }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "InlineRole", "__tag": 4003, "value": "None", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", the " }, { "__type": "InlineRole", "__tag": 4003, "value": "~np.random.RandomState", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " singleton is used. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "seed" }, { "__type": "Text", "__tag": 4046, "value": " is an int, a new " }, { "__type": "InlineCode", "__tag": 4051, "value": "RandomState" }, { "__type": "Text", "__tag": 4046, "value": " instance is used, seeded with seed. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "seed" }, { "__type": "Text", "__tag": 4046, "value": " is already a " }, { "__type": "InlineCode", "__tag": 4051, "value": "RandomState" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "Generator" }, { "__type": "Text", "__tag": 4046, "value": " instance, then that object is used. Default is " }, { "__type": "InlineRole", "__tag": 4003, "value": "None", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "CrossRef", "__tag": 4002, "value": "mu", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "mu" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " keyword specifies the mean direction vector. The " }, { "__type": "CrossRef", "__tag": 4002, "value": "kappa", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "kappa" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " keyword specifies the concentration parameter." } ] } ], "title": [], "level": 0, "target": null }, "Other Parameters": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null } }, "_ordered_sections": [ "Summary", "Extended Summary", "Parameters", "Attributes", "Methods", "Returns", "Yields", "Receives", "Other Parameters", "Raises", "Warns", "Warnings", "Notes" ], "item_file": "/scipy/stats/_multivariate.py", "item_line": 7025, "item_type": "class", "aliases": [ "scipy.stats._multivariate.vonmises_fisher_gen" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "**Visualization of the probability density**\n\nPlot the probability density in three dimensions for increasing\nconcentration parameter. The density is calculated by the ``pdf``\nmethod.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nimport matplotlib.pyplot as plt\nfrom scipy.stats import vonmises_fisher\nfrom matplotlib.colors import Normalize\nn_grid = 100\nu = np.linspace(0, np.pi, n_grid)\nv = np.linspace(0, 2 * np.pi, n_grid)\nu_grid, v_grid = np.meshgrid(u, v)\nvertices = np.stack([np.cos(v_grid) * np.sin(u_grid),\n np.sin(v_grid) * np.sin(u_grid),\n np.cos(u_grid)],\n axis=2)\nx = np.outer(np.cos(v), np.sin(u))\ny = np.outer(np.sin(v), np.sin(u))\nz = np.outer(np.ones_like(u), np.cos(u))\ndef plot_vmf_density(ax, x, y, z, vertices, mu, kappa):\n vmf = vonmises_fisher(mu, kappa)\n pdf_values = vmf.pdf(vertices)\n pdfnorm = Normalize(vmin=pdf_values.min(), vmax=pdf_values.max())\n ax.plot_surface(x, y, z, rstride=1, cstride=1,\n facecolors=plt.cm.viridis(pdfnorm(pdf_values)),\n linewidth=0)\n ax.set_aspect('equal')\n ax.view_init(azim=-130, elev=0)\n ax.axis('off')\n ax.set_title(rf\"$\\kappa={kappa}$\")\nfig, axes = plt.subplots(nrows=1, ncols=3, figsize=(9, 4),\n subplot_kw={\"projection\": \"3d\"})\nleft, middle, right = axes\nmu = np.array([-np.sqrt(0.5), -np.sqrt(0.5), 0])\nplot_vmf_density(left, x, y, z, vertices, mu, 5)\nplot_vmf_density(middle, x, y, z, vertices, mu, 20)\nplot_vmf_density(right, x, y, z, vertices, mu, 100)\nplt.subplots_adjust(top=1, bottom=0.0, left=0.0, right=1.0, wspace=0.)\nplt.show()\n", "execution_status": "success" }, { "__type": "Figure", "__tag": 4024, "value": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "1.17.1", "kind": "assets", "path": "fig-b04b65c3857e5893.png" } }, { "__type": "Text", "__tag": 4046, "value": "\nAs we increase the concentration parameter, the points are getting more\nclustered together around the mean direction.\n\n**Sampling**\n\nDraw 5 samples from the distribution using the ``rvs`` method resulting\nin a 5x3 array.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "rng = np.random.default_rng()\nmu = np.array([0, 0, 1])\nsamples = vonmises_fisher(mu, 20).rvs(5, random_state=rng)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "samples\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nThese samples are unit vectors on the sphere :math:`S^2`. To verify,\nlet us calculate their euclidean norms:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "np.linalg.norm(samples, axis=1)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nPlot 20 observations drawn from the von Mises-Fisher distribution for\nincreasing concentration parameter :math:`\\kappa`. The red dot highlights\nthe mean direction :math:`\\mu`.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "def plot_vmf_samples(ax, x, y, z, mu, kappa):\n vmf = vonmises_fisher(mu, kappa)\n samples = vmf.rvs(20)\n ax.plot_surface(x, y, z, rstride=1, cstride=1, linewidth=0,\n alpha=0.2)\n ax.scatter(samples[:, 0], samples[:, 1], samples[:, 2], c='k', s=5)\n ax.scatter(mu[0], mu[1], mu[2], c='r', s=30)\n ax.set_aspect('equal')\n ax.view_init(azim=-130, elev=0)\n ax.axis('off')\n ax.set_title(rf\"$\\kappa={kappa}$\")\nmu = np.array([-np.sqrt(0.5), -np.sqrt(0.5), 0])\nfig, axes = plt.subplots(nrows=1, ncols=3,\n subplot_kw={\"projection\": \"3d\"},\n figsize=(9, 4))\nleft, middle, right = axes\nplot_vmf_samples(left, x, y, z, mu, 5)\nplot_vmf_samples(middle, x, y, z, mu, 20)\nplot_vmf_samples(right, x, y, z, mu, 100)\nplt.subplots_adjust(top=1, bottom=0.0, left=0.0,\n right=1.0, wspace=0.)\nplt.show()\n", "execution_status": "success" }, { "__type": "Figure", "__tag": 4024, "value": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "1.17.1", "kind": "assets", "path": "fig-72364bc00132c884.png" } }, { "__type": "Text", "__tag": 4046, "value": "\nThe plots show that with increasing concentration :math:`\\kappa` the\nresulting samples are centered more closely around the mean direction.\n\n**Fitting the distribution parameters**\n\nThe distribution can be fitted to data using the ``fit`` method returning\nthe estimated parameters. As a toy example let's fit the distribution to\nsamples drawn from a known von Mises-Fisher distribution.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "mu, kappa = np.array([0, 0, 1]), 20\nsamples = vonmises_fisher(mu, kappa).rvs(1000, random_state=rng)\nmu_fit, kappa_fit = vonmises_fisher.fit(samples)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "mu_fit, kappa_fit\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nWe see that the estimated parameters `mu_fit` and `kappa_fit` are\nvery close to the ground truth parameters." } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.vonmises", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "scipy.stats.vonmises" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Von-Mises Fisher distribution in 2D on a circle" } ] } ], "type": null }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "uniform_direction", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "uniform_direction" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "uniform distribution on the surface of a hypersphere" } ] } ], "type": null } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "seed", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "vonmises_fisher_gen" }, "references": [ ".. [1] Von Mises-Fisher distribution, Wikipedia,", " https://en.wikipedia.org/wiki/Von_Mises%E2%80%93Fisher_distribution", ".. [2] Mardia, K., and Jupp, P. Directional statistics. Wiley, 2000.", ".. [3] J. Wenzel. Numerically stable sampling of the von Mises Fisher", " distribution on S2.", " https://www.mitsuba-renderer.org/~wenzel/files/vmf.pdf", ".. [4] Wood, A. Simulation of the von mises fisher distribution.", " Communications in statistics-simulation and computation 23,", " 1 (1994), 157-164. https://doi.org/10.1080/03610919408813161", ".. [5] geomstats, Github. MIT License. Accessed: 06.01.2023.", " https://github.com/geomstats/geomstats", ".. [6] Miolane, N. et al. Geomstats: A Python Package for Riemannian", " Geometry in Machine Learning. Journal of Machine Learning Research", " 21 (2020). http://jmlr.org/papers/v21/19-027.html" ], "qa": "scipy.stats._multivariate:vonmises_fisher_gen", "arbitrary": [], "local_refs": [ "entropy(mu=None", "fit(data)", "kappa", "kappa=1", "kappa=1)", "logpdf(x", "mu", "mu=None", "pdf(x", "random_state=None)", "rvs(mu=None", "seed", "size=1" ] }