{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "There are several definitions of \"circular median\" in the literature. Seminal references for circular statistics " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": " mention the bisecting property of the circular median and its connection with minimization of the circular mean deviation. However, " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": " prioritizes minimization of the circular mean deviation as the defining property, whereas " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": " requires that \"the majority of the data points are nearer to [the median] than [its antipode]\"." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Although the two definitions produce the same circular median in many cases (unimodal distribution, no ties), " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "3" }, { "__type": "Text", "__tag": 4046, "value": " demonstrates that the two definitions can lead to different - and in fact, entirely opposite - results. " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "3" }, { "__type": "Text", "__tag": 4046, "value": " also compares the arc-distance, bisecting, and geometric medians with one other definition from vector-space literature, and it concludes that the arc-distance median is the only one that provides all four properties under consideration. This, and the fact that the arc-distance definition is used by default in other circular statistics software (e.g. " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "4" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "5" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "6" }, { "__type": "Text", "__tag": 4046, "value": "), contributed to the choice of " }, { "__type": "InlineCode", "__tag": 4051, "value": "'arc-distance'" }, { "__type": "Text", "__tag": 4046, "value": " as the default convention." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "FootnoteReference", "__tag": 4066, "label": "7" }, { "__type": "Text", "__tag": 4046, "value": " addresses the fact that many points - even continuous arcs of the unit circle - may satisfy the definition of an arc-distance or bisecting circular median. It proposes that \"the estimate of the population circular median be the average (circular mean) of all angles satisfying the definition of median\", and that \"for odd samples, the candidate values are the observations themselves\". However, it suggests that \"for even samples, the candidate values are the midpoints of all neighboring observation\". " }, { "__type": "CrossRef", "__tag": 4002, "value": "circmedian", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "circmedian" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " always finds all points " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "among the observations" } ] }, { "__type": "Text", "__tag": 4046, "value": " (and their antipodes, in the " }, { "__type": "InlineCode", "__tag": 4051, "value": "'bisecting'" }, { "__type": "Text", "__tag": 4046, "value": " case) that satisfy the chosen definition of a circular median and returns their circular mean. If the circular mean is poorly defined (i.e. the circular variance is withing a small tolerance of " }, { "__type": "InlineCode", "__tag": 4051, "value": "1.0" }, { "__type": "Text", "__tag": 4046, "value": "), " }, { "__type": "CrossRef", "__tag": 4002, "value": "circmedian", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "circmedian" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " returns NaN." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Beginning in SciPy 1.9, " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.matrix" }, { "__type": "Text", "__tag": 4046, "value": " inputs (not recommended for new code) are converted to " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.ndarray" }, { "__type": "Text", "__tag": 4046, "value": " before the calculation is performed. In this case, the output will be a scalar or " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.ndarray" }, { "__type": "Text", "__tag": 4046, "value": " of appropriate shape rather than a 2D " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.matrix" }, { "__type": "Text", "__tag": 4046, "value": ". Similarly, while masked elements of masked arrays are ignored, the output will be a scalar or " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.ndarray" }, { "__type": "Text", "__tag": 4046, "value": " rather than a masked array with " }, { "__type": "InlineCode", "__tag": 4051, "value": "mask=False" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "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": "circmedian", "annotation": "float", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Circular median, restricted to the range " }, { "__type": "InlineCode", "__tag": 4051, "value": "[low, high]" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Compute the circular median of an angular sample." } ] } ], "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": "sample", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Input array of angle observations." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "convention", "annotation": "{'arc-distance', 'bisecting', 'geometric'}", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Definition of the circular median, following the terminology of " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "3" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An " }, { "__type": "InlineCode", "__tag": 4051, "value": "'arc-distance'" }, { "__type": "Text", "__tag": 4046, "value": " median minimizes the circular mean deviation: the average arc distance between the observations and a common reference angle. Any arc-distance median also has the \"bisecting property\": the chord between a median and its antipode divide the circle in two such that at least half the observations lie in each semicircle." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A " }, { "__type": "InlineCode", "__tag": 4051, "value": "'bisecting'" }, { "__type": "Text", "__tag": 4046, "value": " median has the bisecting property, but does not necessarily minimize the circular mean deviation. Instead, the number of observations within 90 degrees of a bisecting median is greater than the number of observations within 90 degrees of its antipode." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A " }, { "__type": "InlineCode", "__tag": 4051, "value": "'geometric'" }, { "__type": "Text", "__tag": 4046, "value": " median treats angle observations extrinsically: it maps them to points on the unit circle in the ambient two-dimensional vector space, computes their vector median, and extracts the angular phase of the result. A geometric median does not necessarily have the bisecting property, but it is unique unless all points lie on a line, and it is the only convention here that is defined extrinsically, like the circular mean and circular variance." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "3" }, { "__type": "Text", "__tag": 4046, "value": " for precise mathematical definitions." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "high", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Upper boundary of the principal value of an angle. Default is " }, { "__type": "InlineCode", "__tag": 4051, "value": "2*pi" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "low", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Lower boundary of the principal value of an angle. Default is " }, { "__type": "InlineCode", "__tag": 4051, "value": "0" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "axis", "annotation": "int or None, default: None", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If an int, the axis of the input along which to compute the statistic. The statistic of each axis-slice (e.g. row) of the input will appear in a corresponding element of the output. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": ", the input will be raveled before computing the statistic." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "nan_policy", "annotation": "{'propagate', 'omit', 'raise'}", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Defines how to handle input NaNs." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "propagate" }, { "__type": "Text", "__tag": 4046, "value": ": if a NaN is present in the axis slice (e.g. row) along which the statistic is computed, the corresponding entry of the output will be NaN." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "omit" }, { "__type": "Text", "__tag": 4046, "value": ": NaNs will be omitted when performing the calculation. If insufficient data remains in the axis slice along which the statistic is computed, the corresponding entry of the output will be NaN." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "raise" }, { "__type": "Text", "__tag": 4046, "value": ": if a NaN is present, a " }, { "__type": "InlineCode", "__tag": 4051, "value": "ValueError" }, { "__type": "Text", "__tag": 4046, "value": " will be raised." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "nan_policy='raise'" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "nan_policy='omit'" }, { "__type": "Text", "__tag": 4046, "value": " are not supported by lazy backends, and " }, { "__type": "InlineCode", "__tag": 4051, "value": "nan_policy='omit'" }, { "__type": "Text", "__tag": 4046, "value": " is not compatible with MArray input. For multidimensional input, " }, { "__type": "InlineCode", "__tag": 4051, "value": "nan_policy='omit'" }, { "__type": "Text", "__tag": 4046, "value": " is supported only by the NumPy backend. Instead, mask NaN values using " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "MArray" } ], "url": "https://mdhaber.github.io/marray/tutorial.html", "title": "" }, { "__type": "Text", "__tag": 4046, "value": "; and use the default " }, { "__type": "ParamRef", "__tag": 4071, "name": "nan_policy" }, { "__type": "Text", "__tag": 4046, "value": ". See Notes for support information." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "keepdims", "annotation": "bool, default: False", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "According to " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": ", a " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "circular median" } ] }, { "__type": "Text", "__tag": 4046, "value": " is an angle that bisects the data: half of the observations lie within 180 degrees clockwise and half lie within 180 degrees counter-clockwise. The implementation of " }, { "__type": "CrossRef", "__tag": 4002, "value": "circmedian", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "circmedian" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " agrees with these references but follows the details of " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "3" }, { "__type": "Text", "__tag": 4046, "value": ", which defines this \"bisecting property\" more rigorously with consideration for edge cases (e.g. ties, symmetry)." } ] } ], "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": "build-install/usr/lib/python3.14/site-packages/scipy/stats/_circstats.py", "item_line": 84, "item_type": "function", "aliases": [ "scipy.stats.circmedian" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Consider Example 1 from [3]_, expressed in degrees for readability.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy import stats\nsample = np.array([101.25, 101.25, 0, -101.25, -101.25])\n", "execution_status": "success", "out": "" }, { "__type": "Text", "__tag": 4046, "value": "\nThe unique arc-distance median is 0 because it minimizes the mean arc distance to\nthe other observations.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "displacements = (sample[:, np.newaxis] - sample[np.newaxis, :]) % 360\ndistances = np.minimum(displacements, 360 - displacements)\nmean_deviations = np.mean(distances, axis=-1)\nsample[mean_deviations == np.min(mean_deviations)]\n", "execution_status": "success", "out": "array([0.])\n" }, { "__type": "Text", "__tag": 4046, "value": "\nAs expected,\n\n" }, { "__type": "Code", "__tag": 4050, "value": "stats.circmedian(sample, low=-180, high=180)\n", "execution_status": "success", "out": "np.float64(0.0)\n" }, { "__type": "Text", "__tag": 4046, "value": "\nNote that the chord from *any* observation to its antipode bisects the observations\nin this example. Furthermore, each antipode is within 90 degrees of three or four\nobservations, whereas each observation has either two or zero other observations\nwithin 90 degrees. Therefore, the antipodes ``[-78.75, -78.75, 180, 78.75, 78.75]``\nall satisfy the definition of a bisecting median. The circular mean of these is 180\ndegrees,\n\n" }, { "__type": "Code", "__tag": 4050, "value": "stats.circmean([-78.75, -78.75, 180, 78.75, 78.75], low=-180, high=180)\n", "execution_status": "success", "out": "np.float64(179.99999999999994)\n" }, { "__type": "Text", "__tag": 4046, "value": "\nand so:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "stats.circmedian(sample, low=-180, high=180, convention='bisecting')\n", "execution_status": "success", "out": "np.float64(179.99999999999994)\n" }, { "__type": "Text", "__tag": 4046, "value": "\nThe discrepancy between the two conventions is extreme in this constructed example,\nbut for data from a unimodal, continuous distribution, the two definitions tend to\nproduce similar or identical results.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "rng = np.random.default_rng(8180124976)\nsample = rng.vonmises(mu=0, kappa=1, size=10)\nstats.circmedian(sample), stats.circmedian(sample, convention='bisecting')\n", "execution_status": "success", "out": "(np.float64(0.44401177698735417), np.float64(0.44401177698735417))\n" } ], "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._circstats:circmean" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Circular mean." } ] } ], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "circstd", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._circstats:circstd" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Circular standard deviation." } ] } ], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "circvar", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._circstats:circvar" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Circular variance." } ] } ], "type": "func" } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "sample", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "convention", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "arc-distance" }, { "__type": "SigParam", "__tag": 4030, "name": "high", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "6.283185307179586" }, { "__type": "SigParam", "__tag": 4030, "name": "low", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "0" }, { "__type": "SigParam", "__tag": 4030, "name": "axis", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "0" }, { "__type": "SigParam", "__tag": 4030, "name": "nan_policy", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "propagate" }, { "__type": "SigParam", "__tag": 4030, "name": "keepdims", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "False" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "circmedian" }, "references": [ ".. [1] Fisher, Nicholas I. *Statistical Analysis of Circular Data*. Cambridge", " University Press, 1995.", ".. [2] Mardia, K. V. and Jupp, P. E. *Directional Statistics*.", " John Wiley & Sons, 1999.", ".. [3] Storath, Martin, and Andreas Weinmann. \"Fast median filtering for phase or", " orientation data.\" *IEEE Transactions on Pattern Analysis and Machine", " Intelligence* 40.3 (2017): 639-652.", ".. [4] Berens, Philipp. \"CircStat: a MATLAB toolbox for circular statistics.\"", " *Journal of Statistical Software* 31 (2009): 1-21.", ".. [5] Lund, Ulric, Claudio Agostinelli, and Maintainer Claudio Agostinelli.", " \"Package 'circular'.\" Repository CRAN 775.5 (2017): 20-135.", ".. [6] Huang, Ziwei. \"PyCircStat2: Circular statistics with Python\".", " https://github.com/circstat/pycircstat2.", ".. [7] Otieno, B., and Christine M. Anderson-Cook. \"A more efficient way of", " obtaining a unique median estimate for circular data.\" *Journal of Modern", " Applied Statistical Methods* 2.1 (2003): 15." ], "qa": "scipy.stats._circstats:circmedian", "arbitrary": [], "local_refs": [ "axis", "circmedian", "convention", "high", "keepdims", "low", "nan_policy", "sample" ] }