{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Assume that the observations are in the columns of the observation array " }, { "__type": "ParamRef", "__tag": 4071, "name": "m" }, { "__type": "Text", "__tag": 4046, "value": " and let " }, { "__type": "InlineCode", "__tag": 4051, "value": "f = fweights" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "a = aweights" }, { "__type": "Text", "__tag": 4046, "value": " for brevity. The steps to compute the weighted covariance are as follows " } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> m = np.arange(10, dtype=np.float64)\n>>> f = np.arange(10) * 2\n>>> a = np.arange(10) ** 2.\n>>> ddof = 1\n>>> w = f * a\n>>> v1 = np.sum(w)\n>>> v2 = np.sum(w * a)\n>>> m -= np.sum(m * w, axis=None, keepdims=True) / v1\n>>> cov = np.dot(m * w, m.T) * v1 / (v1**2 - ddof * v2)", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Note that when " }, { "__type": "InlineCode", "__tag": 4051, "value": "a == 1" }, { "__type": "Text", "__tag": 4046, "value": ", the normalization factor " }, { "__type": "InlineCode", "__tag": 4051, "value": "v1 / (v1**2 - ddof * v2)" }, { "__type": "Text", "__tag": 4046, "value": " goes over to " }, { "__type": "InlineCode", "__tag": 4051, "value": "1 / (np.sum(f) - ddof)" }, { "__type": "Text", "__tag": 4046, "value": " as it should." } ] } ], "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 covariance matrix of the variables." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Estimate a covariance matrix, given data and weights." } ] } ], "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": "m", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A 1-D or 2-D array containing multiple variables and observations. Each row of " }, { "__type": "ParamRef", "__tag": 4071, "name": "m" }, { "__type": "Text", "__tag": 4046, "value": " represents a variable, and each column a single observation of all those variables. Also see " }, { "__type": "ParamRef", "__tag": 4071, "name": "rowvar" }, { "__type": "Text", "__tag": 4046, "value": " below." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "y", "annotation": "array_like, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An additional set of variables and observations. " }, { "__type": "ParamRef", "__tag": 4071, "name": "y" }, { "__type": "Text", "__tag": 4046, "value": " has the same form as that of " }, { "__type": "ParamRef", "__tag": 4071, "name": "m" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "rowvar", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "rowvar" }, { "__type": "Text", "__tag": 4046, "value": " is True (default), then each row represents a variable, with observations in the columns. Otherwise, the relationship is transposed: each column represents a variable, while the rows contain observations." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "bias", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Default normalization (False) is by " }, { "__type": "InlineCode", "__tag": 4051, "value": "(N - 1)" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineCode", "__tag": 4051, "value": "N" }, { "__type": "Text", "__tag": 4046, "value": " is the number of observations given (unbiased estimate). If " }, { "__type": "ParamRef", "__tag": 4071, "name": "bias" }, { "__type": "Text", "__tag": 4046, "value": " is True, then normalization is by " }, { "__type": "InlineCode", "__tag": 4051, "value": "N" }, { "__type": "Text", "__tag": 4046, "value": ". These values can be overridden by using the keyword " }, { "__type": "InlineCode", "__tag": 4051, "value": "ddof" }, { "__type": "Text", "__tag": 4046, "value": " in numpy versions >= 1.5." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "ddof", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If not " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": " the default value implied by " }, { "__type": "ParamRef", "__tag": 4071, "name": "bias" }, { "__type": "Text", "__tag": 4046, "value": " is overridden. Note that " }, { "__type": "InlineCode", "__tag": 4051, "value": "ddof=1" }, { "__type": "Text", "__tag": 4046, "value": " will return the unbiased estimate, even if both " }, { "__type": "ParamRef", "__tag": 4071, "name": "fweights" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "ParamRef", "__tag": 4071, "name": "aweights" }, { "__type": "Text", "__tag": 4046, "value": " are specified, and " }, { "__type": "InlineCode", "__tag": 4051, "value": "ddof=0" }, { "__type": "Text", "__tag": 4046, "value": " will return the simple average. See the notes for the details. The default value is " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "fweights", "annotation": "array_like, int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "1-D array of integer frequency weights; the number of times each observation vector should be repeated." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "aweights", "annotation": "array_like, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "1-D array of observation vector weights. These relative weights are typically large for observations considered \"important\" and smaller for observations considered less \"important\". If " }, { "__type": "InlineCode", "__tag": 4051, "value": "ddof=0" }, { "__type": "Text", "__tag": 4046, "value": " the array of weights can be used to assign probabilities to observation vectors." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "dtype", "annotation": "data-type, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Data-type of the result. By default, the return data-type will have at least " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.float64", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:float64" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " precision." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 1.20" } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Covariance indicates the level to which two variables vary together. If we examine N-dimensional samples, " }, { "__type": "InlineMath", "__tag": 4057, "value": "X = [x_1, x_2, ..., x_N]^T" }, { "__type": "Text", "__tag": 4046, "value": ", then 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": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See the notes for an outline of the algorithm." } ] } ], "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": "/numpy/lib/_function_base_impl.py", "item_line": 2674, "item_type": "_ArrayFunctionDispatcher", "aliases": [ "numpy.cov" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import numpy as np\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nConsider two variables, :math:`x_0` and :math:`x_1`, which\ncorrelate perfectly, but in opposite directions:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "x = np.array([[0, 2], [1, 1], [2, 0]]).T\nx\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nNote how :math:`x_0` increases while :math:`x_1` decreases. The covariance\nmatrix shows this clearly:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "np.cov(x)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nNote that element :math:`C_{0,1}`, which shows the correlation between\n:math:`x_0` and :math:`x_1`, is negative.\n\nFurther, note how `x` and `y` are combined:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "x = [-2.1, -1, 4.3]\ny = [3, 1.1, 0.12]\nX = np.stack((x, y), axis=0)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "np.cov(X)\nnp.cov(x, y)\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "np.cov(x)\n", "execution_status": "success" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "corrcoef", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "corrcoef" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Normalized covariance matrix" } ] } ], "type": null } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "m", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "y", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "rowvar", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "True" }, { "__type": "SigParam", "__tag": 4030, "name": "bias", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "ddof", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "fweights", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "aweights", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "dtype", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "cov" }, "references": null, "qa": "numpy:cov", "arbitrary": [], "local_refs": [ "aweights", "bias", "ddof", "dtype", "fweights", "m", "out", "rowvar", "y" ] }