{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The mean is a coordinate in N-dimensional space, which represents the location where samples are most likely to be generated. This is analogous to the peak of the bell curve for the one-dimensional or univariate normal distribution." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Covariance indicates the level to which two variables vary together. From the multivariate normal distribution, we draw N-dimensional samples, " }, { "__type": "InlineMath", "__tag": 4057, "value": "X = [x_1, x_2, ... x_N]" }, { "__type": "Text", "__tag": 4046, "value": ". The covariance matrix element " }, { "__type": "InlineMath", "__tag": 4057, "value": "C_{ij}" }, { "__type": "Text", "__tag": 4046, "value": " is the covariance of " }, { "__type": "InlineMath", "__tag": 4057, "value": "x_i" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineMath", "__tag": 4057, "value": "x_j" }, { "__type": "Text", "__tag": 4046, "value": ". The element " }, { "__type": "InlineMath", "__tag": 4057, "value": "C_{ii}" }, { "__type": "Text", "__tag": 4046, "value": " is the variance of " }, { "__type": "InlineMath", "__tag": 4057, "value": "x_i" }, { "__type": "Text", "__tag": 4046, "value": " (i.e. its \"spread\")." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Instead of specifying the full covariance matrix, popular approximations include:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Spherical covariance (" }, { "__type": "ParamRef", "__tag": 4071, "name": "cov" }, { "__type": "Text", "__tag": 4046, "value": " is a multiple of the identity matrix)" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Diagonal covariance (" }, { "__type": "ParamRef", "__tag": 4071, "name": "cov" }, { "__type": "Text", "__tag": 4046, "value": " has non-negative elements, and only on the diagonal)" } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This geometrical property can be seen in two dimensions by plotting generated data-points:" } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> mean = [0, 0]\n>>> cov = [[1, 0], [0, 100]] # diagonal covariance", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Diagonal covariance means that the variables are independent, and the probability density contours have their axes aligned with the coordinate axes:" } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> import matplotlib.pyplot as plt\n>>> x, y = np.random.multivariate_normal(mean, cov, 5000).T\n>>> plt.plot(x, y, 'x')\n>>> plt.axis('equal')\n>>> plt.show()", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Note that the covariance matrix must be positive semidefinite (a.k.a. nonnegative-definite). Otherwise, the behavior of this method is undefined and backwards compatibility is not guaranteed." } ] } ], "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": [], "title": [], "level": 0, "target": null }, "Returns": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "out", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The drawn samples, of shape " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "size" } ] }, { "__type": "Text", "__tag": 4046, "value": ", if that was provided. If not, the shape is " }, { "__type": "InlineCode", "__tag": 4051, "value": "(N,)" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In other words, each entry " }, { "__type": "InlineCode", "__tag": 4051, "value": "out[i,j,...,:]" }, { "__type": "Text", "__tag": 4046, "value": " is an N-dimensional value drawn from the distribution." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Draw random samples from a multivariate normal distribution." } ] } ], "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": "mean", "annotation": "1-D array_like, of length N", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Mean of the N-dimensional distribution." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "cov", "annotation": "2-D array_like, of shape (N, N)", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Covariance matrix of the distribution. It must be symmetric and positive-semidefinite for proper sampling." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "size", "annotation": "int or tuple of ints, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Given a shape of, for example, " }, { "__type": "InlineCode", "__tag": 4051, "value": "(m,n,k)" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "m*n*k" }, { "__type": "Text", "__tag": 4046, "value": " samples are generated, and packed in an " }, { "__type": "InlineRole", "__tag": 4003, "value": "m", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "-by-" }, { "__type": "InlineRole", "__tag": 4003, "value": "n", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "-by-" }, { "__type": "InlineRole", "__tag": 4003, "value": "k", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " arrangement. Because each sample is " }, { "__type": "InlineRole", "__tag": 4003, "value": "N", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "-dimensional, the output shape is " }, { "__type": "InlineCode", "__tag": 4051, "value": "(m,n,k,N)" }, { "__type": "Text", "__tag": 4046, "value": ". If no shape is specified, a single (" }, { "__type": "InlineRole", "__tag": 4003, "value": "N", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "-D) sample is returned." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "check_valid", "annotation": "{ 'warn', 'raise', 'ignore' }, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Behavior when the covariance matrix is not positive semidefinite." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "tol", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Tolerance when checking the singular values in covariance matrix. cov is cast to double before the check." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The multivariate normal, multinormal or Gaussian distribution is a generalization of the one-dimensional normal distribution to higher dimensions. Such a distribution is specified by its mean and covariance matrix. These parameters are analogous to the mean (average or \"center\") and variance (standard deviation, or \"width,\" squared) of the one-dimensional normal distribution." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "note", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "note " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "New code should use the " }, { "__type": "CrossRef", "__tag": 4002, "value": "multivariate_normal", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy.random._generator:Generator.multivariate_normal" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " method of a " }, { "__type": "CrossRef", "__tag": 4002, "value": "Generator", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy.random._generator:Generator" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " instance instead; please see the " }, { "__type": "InlineRole", "__tag": 4003, "value": "random-quick-start", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ], "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": null, "item_line": null, "item_type": "cython_function_or_method", "aliases": [ "numpy.random.multivariate_normal", "numpy.random.RandomState.multivariate_normal" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "mean = (1, 2)\ncov = [[1, 0], [0, 1]]\nx = np.random.multivariate_normal(mean, cov, (3, 3))\nx.shape\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nHere we generate 800 samples from the bivariate normal distribution\nwith mean [0, 0] and covariance matrix [[6, -3], [-3, 3.5]]. The\nexpected variances of the first and second components of the sample\nare 6 and 3.5, respectively, and the expected correlation\ncoefficient is -3/sqrt(6*3.5) ≈ -0.65465.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "cov = np.array([[6, -3], [-3, 3.5]])\npts = np.random.multivariate_normal([0, 0], cov, size=800)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nCheck that the mean, covariance, and correlation coefficient of the\nsample are close to the expected values:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "pts.mean(axis=0)\nnp.cov(pts.T)\nnp.corrcoef(pts.T)[0, 1]\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nWe can visualize this data with a scatter plot. The orientation\nof the point cloud illustrates the negative correlation of the\ncomponents of this sample.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import matplotlib.pyplot as plt\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "plt.plot(pts[:, 0], pts[:, 1], '.', alpha=0.5)\nplt.axis('equal')\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "plt.grid()\nplt.show()\n", "execution_status": "success" }, { "__type": "Figure", "__tag": 4024, "value": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "2.4.3", "kind": "assets", "path": "fig-3d41906365f3822e.png" } } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "random.Generator.multivariate_normal", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "random.Generator.multivariate_normal" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "which should be used for new code." } ] } ], "type": null } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "mean", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "cov", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "size", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "check_valid", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "warn" }, { "__type": "SigParam", "__tag": 4030, "name": "tol", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "1e-08" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "multivariate_normal" }, "references": [ ".. [1] Papoulis, A., \"Probability, Random Variables, and Stochastic", " Processes,\" 3rd ed., New York: McGraw-Hill, 1991.", ".. [2] Duda, R. O., Hart, P. E., and Stork, D. G., \"Pattern", " Classification,\" 2nd ed., New York: Wiley, 2001." ], "qa": "numpy.random:RandomState.multivariate_normal", "arbitrary": [], "local_refs": [ "check_valid", "cov", "mean", "out", "size", "tol" ] }