{
    "nbformat": 4,
    "nbformat_minor": 5,
    "metadata": {
        "kernelspec": {
            "display_name": "Python",
            "language": "python",
            "name": "python"
        },
        "language_info": {
            "name": "python"
        }
    },
    "cells": [
        {
            "id": "472e2098",
            "cell_type": "markdown",
            "source": "<div class='alert alert-warning'>\n\nSciPy's interactive examples with Jupyterlite are experimental and may not always work as expected. Execution of cells containing imports may result in large downloads (up to 60MB of content for the first import from SciPy). Load times when importing from SciPy may take roughly 10-20 seconds. If you notice any problems, feel free to open an [issue](https://github.com/scipy/scipy/issues/new/choose).\n\n</div>",
            "metadata": {}
        },
        {
            "id": "ea22a518",
            "cell_type": "code",
            "metadata": {},
            "execution_count": null,
            "source": "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",
            "outputs": [
                {
                    "output_type": "execute_result",
                    "metadata": {},
                    "data": {
                        "text/plain": "array([1., 0.])"
                    },
                    "execution_count": null
                }
            ]
        },
        {
            "id": "6c8beb5d",
            "cell_type": "markdown",
            "source": "In 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",
            "metadata": {}
        },
        {
            "id": "d567f8f8",
            "cell_type": "code",
            "metadata": {},
            "execution_count": null,
            "source": "data.mean(axis=0)",
            "outputs": [
                {
                    "output_type": "execute_result",
                    "metadata": {},
                    "data": {
                        "text/plain": "array([4.5, -2.])"
                    },
                    "execution_count": null
                }
            ]
        },
        {
            "id": "9ee5290d",
            "cell_type": "markdown",
            "source": "An 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",
            "metadata": {}
        },
        {
            "id": "e5abbfeb",
            "cell_type": "code",
            "metadata": {},
            "execution_count": null,
            "source": "data = np.array([[0.8660254, 0.5, 0.],\n                 [0.8660254, -0.5, 0.]])\ndirstats = directional_stats(data)\ndirstats.mean_direction",
            "outputs": [
                {
                    "output_type": "execute_result",
                    "metadata": {},
                    "data": {
                        "text/plain": "array([1., 0., 0.])"
                    },
                    "execution_count": null
                }
            ]
        },
        {
            "id": "e6bff0b7",
            "cell_type": "markdown",
            "source": "The regular sample mean on the other hand yields a result which does not\nlie on the surface of the sphere.\n",
            "metadata": {}
        },
        {
            "id": "709b7e36",
            "cell_type": "code",
            "metadata": {},
            "execution_count": null,
            "source": "data.mean(axis=0)",
            "outputs": [
                {
                    "output_type": "execute_result",
                    "metadata": {},
                    "data": {
                        "text/plain": "array([0.8660254, 0., 0.])"
                    },
                    "execution_count": null
                }
            ]
        },
        {
            "id": "8627f43f",
            "cell_type": "markdown",
            "source": "The 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",
            "metadata": {}
        },
        {
            "id": "bc8ea408",
            "cell_type": "code",
            "metadata": {},
            "execution_count": null,
            "source": "1 - dirstats.mean_resultant_length",
            "outputs": [
                {
                    "output_type": "execute_result",
                    "metadata": {},
                    "data": {
                        "text/plain": "0.13397459716167093"
                    },
                    "execution_count": null
                }
            ]
        }
    ]
}