{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This uses a definition of directional mean from " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": ". Assuming the observations are unit vectors, the calculation is as follows." } ] }, { "__type": "Code", "__tag": 4050, "value": "mean = samples.mean(axis=0)\nmean_resultant_length = np.linalg.norm(mean)\nmean_direction = mean / mean_resultant_length", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This definition is appropriate for " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "directional" } ] }, { "__type": "Text", "__tag": 4046, "value": " data (i.e. vector data for which the magnitude of each observation is irrelevant) but not for " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axial" } ] }, { "__type": "Text", "__tag": 4046, "value": " data (i.e. vector data for which the magnitude and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "sign" } ] }, { "__type": "Text", "__tag": 4046, "value": " of each observation is irrelevant)." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Several definitions of directional variance involving the mean resultant length " }, { "__type": "InlineCode", "__tag": 4051, "value": "R" }, { "__type": "Text", "__tag": 4046, "value": " have been proposed, including " }, { "__type": "InlineCode", "__tag": 4051, "value": "1 - R" }, { "__type": "Text", "__tag": 4046, "value": " " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "1 - R**2" }, { "__type": "Text", "__tag": 4046, "value": " " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": ", and " }, { "__type": "InlineCode", "__tag": 4051, "value": "2 * (1 - R)" }, { "__type": "Text", "__tag": 4046, "value": " " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": ". Rather than choosing one, this function returns " }, { "__type": "InlineCode", "__tag": 4051, "value": "R" }, { "__type": "Text", "__tag": 4046, "value": " as attribute " }, { "__type": "InlineRole", "__tag": 4003, "value": "mean_resultant_length", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " so the user can compute their preferred measure of dispersion." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Array API Standard Support" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "directional_stats", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._morestats:directional_stats" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " has experimental support for Python Array API Standard compatible backends in addition to NumPy. Please consider testing these features by setting an environment variable " }, { "__type": "InlineCode", "__tag": 4051, "value": "SCIPY_ARRAY_API=1" }, { "__type": "Text", "__tag": 4046, "value": " and providing CuPy, PyTorch, JAX, or Dask arrays as array arguments. The following combinations of backend and device (or other capability) are supported." } ] }, { "__type": "Code", "__tag": 4050, "value": "==================== ==================== ====================\nLibrary CPU GPU\n==================== ==================== ====================\nNumPy ✅ n/a \nCuPy n/a ✅ \nPyTorch ✅ ✅ \nJAX ✅ ✅ \nDask ✅ n/a \n==================== ==================== ====================", "execution_status": null }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See " }, { "__type": "InlineRole", "__tag": 4003, "value": "dev-arrayapi", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for more information." } ] } ] } ], "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": "res", "annotation": "DirectionalStats", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An object containing attributes:" } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "mean_direction" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "mean_direction" } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "mean_resultant_length" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "mean_resultant_length" } ] } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Computes sample statistics for directional data." } ] } ], "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": "samples", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Input array. Must be at least two-dimensional, and the last axis of the input must correspond with the dimensionality of the vector space. When the input is exactly two dimensional, this means that each row of the data is a vector observation." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "axis", "annotation": "int, default: 0", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Axis along which the directional mean is computed." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "normalize: boolean, default: True", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If True, normalize the input to ensure that each observation is a unit vector. It the observations are already unit vectors, consider setting this to False to avoid unnecessary computation." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Computes the directional mean (also called the mean direction vector) and mean resultant length of a sample of vectors." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The directional mean is a measure of \"preferred direction\" of vector data. It is analogous to the sample mean, but it is for use when the length of the data is irrelevant (e.g. unit vectors)." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The mean resultant length is a value between 0 and 1 used to quantify the dispersion of directional data: the smaller the mean resultant length, the greater the dispersion. Several definitions of directional variance involving the mean resultant length are given in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__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": "/scipy/stats/_morestats.py", "item_line": 4497, "item_type": "function", "aliases": [ "scipy.stats.directional_stats" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy.stats import directional_stats\ndata = np.array([[3, 4], # first observation, 2D vector space\n [6, -8]]) # second observation\ndirstats = directional_stats(data)\ndirstats.mean_direction\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nIn contrast, the regular sample mean of the vectors would be influenced\nby the magnitude of each observation. Furthermore, the result would not be\na unit vector.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "data.mean(axis=0)\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nAn exemplary use case for `directional_stats` is to find a *meaningful*\ncenter for a set of observations on a sphere, e.g. geographical locations.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "data = np.array([[0.8660254, 0.5, 0.],\n [0.8660254, -0.5, 0.]])\ndirstats = directional_stats(data)\ndirstats.mean_direction\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe regular sample mean on the other hand yields a result which does not\nlie on the surface of the sphere.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "data.mean(axis=0)\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nThe function also returns the mean resultant length, which\ncan be used to calculate a directional variance. For example, using the\ndefinition ``Var(z) = 1 - R`` from [2]_ where ``R`` is the\nmean resultant length, we can calculate the directional variance of the\nvectors in the above example as:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "1 - dirstats.mean_resultant_length\n", "execution_status": "failure" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "circmean", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._morestats:circmean" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "circular mean; i.e. directional mean for 2D " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "angles" } ] } ] } ], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "circvar", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._morestats:circvar" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "circular variance; i.e. directional variance for 2D " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "angles" } ] } ] } ], "type": "func" } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "samples", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "axis", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "0" }, { "__type": "SigParam", "__tag": 4030, "name": "normalize", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "True" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "directional_stats" }, "references": [ ".. [1] Mardia, Jupp. (2000). *Directional Statistics*", " (p. 163). Wiley.", "", ".. [2] https://en.wikipedia.org/wiki/Directional_statistics" ], "qa": "scipy.stats._morestats:directional_stats", "arbitrary": [], "local_refs": [ "axis", "default: True", "normalize: boolean", "res", "samples" ] }