ocelot 0.3.1a0__tar.gz

ocelot-0.3.1a0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Emily Hunt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ocelot-0.3.1a0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.1
+Name: ocelot
+Version: 0.3.1a0
+Summary: A toolbox for working with observations of star clusters.
+Author-email: Emily Hunt <emily.hunt.physics@gmail.com>
+Maintainer-email: Emily Hunt <emily.hunt.physics@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2023 Emily Hunt
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://ocelot-docs.org
+Project-URL: Bug Reports, https://github.com/emilyhunt/ocelot/issues
+Project-URL: Source, https://github.com/emilyhunt/ocelot
+Keywords: astronomy,star cluster,threading,development
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3.0,>1.21.0
+Requires-Dist: matplotlib<4.0,>3.4.0
+Requires-Dist: scikit-learn<2.0,>0.24.0
+Requires-Dist: scipy<2.0,>1.0.0
+Requires-Dist: pandas<3.0,>1.0.0
+Requires-Dist: astropy<7.0,>4.0.0
+Requires-Dist: healpy<2.0,>1.13.0
+Provides-Extra: dev
+Requires-Dist: check-manifest; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: mkdocs-material[imaging]; extra == "dev"
+Requires-Dist: mkdocstrings[python]>=0.18; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material[imaging]; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.18; extra == "docs"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+
+[![docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://ocelot-docs.org)
+[![Build Docs](https://github.com/emilyhunt/ocelot/actions/workflows/build-docs.yml/badge.svg)](https://ocelot-docs.org)
+
+# ocelot
+
+A toolbox for working with observations of star clusters. 
+
+In the [long-running tradition](https://arxiv.org/abs/1903.12180) of astronomy software, `ocelot` is _not_ a good acronym for this project. It's the **O**pen-source star **C**lust**E**r mu**L**ti-purp**O**se **T**oolkit. (We hope the results you get from this package are better than this acronym)
+
+## Current package status
+
+⚠️ ocelot is currently in **alpha** and is in active development. **Expect breaking API changes** ⚠️
+
+For the time being, `ocelot` is a collection of code that [emilyhunt](https://github.com/emilyhunt) wrote during her PhD, but the eventual goal will be to make a package usable by the entire star cluster community. If you'd like to see a feature added, then please consider opening an issue and proposing it!
+
+## Installation
+
+Install from PyPI with:
+
+```
+pip install ocelot
+```
+
+## Development
+
+If you'd like to contribute to the package, we recommend setting up a new virtual environment of your choice. Then, you can install the latest commit on the main branch in edit mode (`-e`) with all development dependencies (`[dev]`) with:
+
+```
+pip install -e git+https://github.com/emilyhunt/ocelot[dev]
+```
+
+After installing development dependencies, you can also make and view edits to the package's documentation. To view a local copy of the documentation, do `mkdocs serve`. You can do a test build with `mkdocs build`.

ocelot-0.3.1a0/README.md

@@ -0,0 +1,32 @@
+[![docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://ocelot-docs.org)
+[![Build Docs](https://github.com/emilyhunt/ocelot/actions/workflows/build-docs.yml/badge.svg)](https://ocelot-docs.org)
+
+# ocelot
+
+A toolbox for working with observations of star clusters. 
+
+In the [long-running tradition](https://arxiv.org/abs/1903.12180) of astronomy software, `ocelot` is _not_ a good acronym for this project. It's the **O**pen-source star **C**lust**E**r mu**L**ti-purp**O**se **T**oolkit. (We hope the results you get from this package are better than this acronym)
+
+## Current package status
+
+⚠️ ocelot is currently in **alpha** and is in active development. **Expect breaking API changes** ⚠️
+
+For the time being, `ocelot` is a collection of code that [emilyhunt](https://github.com/emilyhunt) wrote during her PhD, but the eventual goal will be to make a package usable by the entire star cluster community. If you'd like to see a feature added, then please consider opening an issue and proposing it!
+
+## Installation
+
+Install from PyPI with:
+
+```
+pip install ocelot
+```
+
+## Development
+
+If you'd like to contribute to the package, we recommend setting up a new virtual environment of your choice. Then, you can install the latest commit on the main branch in edit mode (`-e`) with all development dependencies (`[dev]`) with:
+
+```
+pip install -e git+https://github.com/emilyhunt/ocelot[dev]
+```
+
+After installing development dependencies, you can also make and view edits to the package's documentation. To view a local copy of the documentation, do `mkdocs serve`. You can do a test build with `mkdocs build`.

ocelot-0.3.1a0/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "ocelot"  # Required
+version = "0.3.1-alpha"  # Required
+description = "A toolbox for working with observations of star clusters."  # Optional
+readme = "README.md" # Optional
+requires-python = ">=3.8"
+license = {file = "LICENSE"}
+keywords = ["astronomy", "star cluster", "threading", "development"]  # Optional
+authors = [
+  {name = "Emily Hunt", email = "emily.hunt.physics@gmail.com" } # Optional
+]
+maintainers = [
+  {name = "Emily Hunt", email = "emily.hunt.physics@gmail.com" } # Optional
+]
+classifiers = [  # Optional
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3 :: Only",
+]
+dependencies = [
+  "numpy>1.21.0,<3.0",
+  "matplotlib>3.4.0,<4.0",
+  "scikit-learn>0.24.0,<2.0",
+  "scipy>1.0.0,<2.0",
+  "pandas>1.0.0,<3.0",
+  "astropy>4.0.0,<7.0",
+  "healpy>1.13.0,<2.0",
+]
+
+
+[project.optional-dependencies]
+dev = ["check-manifest", "pytest", "mkdocs-material[imaging]", "mkdocstrings[python]>=0.18"]
+docs = ["mkdocs-material[imaging]", "mkdocstrings[python]>=0.18"]  # For building docs on GitHub
+test = ["pytest"]
+
+[project.urls]  # Optional
+"Homepage" = "https://ocelot-docs.org"
+"Bug Reports" = "https://github.com/emilyhunt/ocelot/issues"
+"Source" = "https://github.com/emilyhunt/ocelot"
+
+# [tool.setuptools]
+# package-data = {"sample" = ["*.dat"]}
+
+[tool.pytest.ini_options]
+pythonpath = "src"
+addopts = [
+    "--import-mode=importlib",
+]
+
+[build-system]
+requires = ["setuptools>=43.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.ruff]
+line-length = 88

ocelot-0.3.1a0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ocelot-0.3.1a0/src/ocelot/__init__.py

@@ -0,0 +1 @@
+__version__ = '0.4.0'

ocelot-0.3.1a0/src/ocelot/calculate/__init__.py

@@ -0,0 +1 @@
+# Todo decide what to make top-level here

ocelot-0.3.1a0/src/ocelot/calculate/calculate.py

@@ -0,0 +1,207 @@
+"""A set of functions for calculating typical cluster parameters.
+
+Todo: error treatment here could be made more bayesian
+"""
+
+from typing import Optional
+from astropy.coordinates import SkyCoord
+
+import numpy as np
+import pandas as pd
+
+from .constants import mas_per_yr_to_rad_per_s, pc_to_m, deg_to_rad
+
+
+def _handle_ra_discontinuity(ra_data, middle_ras_raise_error=True):
+    """Tries to detect when the ras in a field cross the (0, 360) ra discontinuity and returns corrected results. Will
+    raise an error if ras are all over the place (which will happen e.g. at very high declinations) in which you
+    ought to instead switch to a method free of spherical distortions.
+
+    Args:
+        ra_data (pd.Series or np.ndarray): data on ras.
+        middle_ras_raise_error (bool): whether or not a cluster having right ascensions in all ranges [0, 90), [90, 270]
+            and (270, 360] raises an error. The error here indicates that this cluster has extreme spherical
+            discontinuities (e.g. it's near a coordinate pole) and that the mean ra and mean dec will be inaccurate.
+            Default: True
+
+    Returns:
+        ra_data but corrected for distortions. If values are both <90 and >270, the new ra data will be in the range
+            (-90, 90).
+
+    """
+    # Firstly, check that the ras are valid ras
+    if np.any(ra_data >= 360) or np.any(ra_data < 0):
+        raise ValueError(
+            "at least one input ra value was invalid! Ras must be in the range [0, 360)."
+        )
+
+    # Next, grab all the locations of dodgy friends and check that all three aren't ever in use at the same time
+    low_ra = ra_data < 90
+    high_ra = ra_data > 270
+    middle_ra = np.logical_not(np.logical_or(low_ra, high_ra))
+
+    # Proceed if we have both low and high ras
+    if np.any(low_ra) and np.any(high_ra):
+        # Stop if we have middle too (would imply stars everywhere or an extreme dec value)
+        if np.any(middle_ra) and middle_ras_raise_error:
+            raise ValueError(
+                "ra values are in all three ranges: [0, 90), [90, 270] and (270, 360). This cluster can't "
+                "be processed by this function! Spherical distortions must be removed first."
+            )
+
+        # Otherwise, apply the discontinuity removal
+        else:
+            # Make a copy so nothing weird happens
+            ra_data = ra_data.copy()
+
+            # And remove the distortion for all high numbers
+            ra_data[high_ra] = ra_data[high_ra] - 360
+
+    return ra_data
+
+
+def mean_radius(
+    data_gaia: pd.DataFrame,
+    membership_probabilities: Optional[np.ndarray] = None,
+    already_inferred_parameters: Optional[dict] = None,
+    key_ra: str = "ra",
+    key_ra_error: str = "ra_error",
+    key_dec: str = "dec",
+    key_dec_error: str = "dec_error",
+    distance_to_use: str = "inverse_parallax",
+    middle_ras_raise_error: bool = True,
+    **kwargs,
+):
+    """Produces various radius statistics on a given cluster, finding its sky location and three radii: the core, tidal
+    and 50% radius.
+
+    Done in a very basic, frequentist way, whereby means are weighted based on the membership probabilities (if
+    specified).
+
+    N.B. unlike the above functions, errors do *not change the mean* as this would potentially bias the
+    estimates towards being dominated by large, centrally-located stars within clusters (that have generally lower
+    velocities.) Hence, estimates here will be less precise but hopefully more accurate.
+
+    Todo: add error estimation to this function (hard)
+
+    Todo: add galactic l, b to the output of this function
+
+    Args:
+        data_gaia (pd.DataFrame): Gaia data for the cluster in the standard format (e.g. as in DR2.)
+        membership_probabilities (optional, np.ndarray): membership probabilities for the cluster. When specified,
+            they can increase or decrease the effect of certain stars on the mean.
+        already_inferred_parameters (optional, dict): a parameter dictionary of the mean distance and proper motion.
+            Otherwise, this function calculates a version.
+        key_ra (str): Gaia parameter name.
+        key_ra_error (str): Gaia parameter name.
+        key_dec (str): Gaia parameter name.
+        key_dec_error (str): Gaia parameter name.
+        distance_to_use (str): which already inferred distance to use to convert angular radii to parsecs.
+            Default: "inverse_parallax"
+        middle_ras_raise_error (bool): whether or not a cluster having right ascensions in all ranges [0, 90), [90, 270]
+            and (270, 360] raises an error. The error here indicates that this cluster has extreme spherical
+            discontinuities (e.g. it's near a coordinate pole) and that the mean ra and mean dec will be inaccurate.
+            Default: True
+
+    Returns:
+        a dict, formatted with:
+            {
+            # Position
+            "ra": ra of the cluster
+            "ra_error": error on the above
+            "dec": dec of the cluster
+            "dec_error": error on the above
+
+            # Angular radii
+            "ang_radius_50": median ang. distance from the center, i.e.angular radius of the cluster with 50% of members
+            "ang_radius_50_error": error on the above
+            "ang_radius_c": angular King's core radius of the cluster
+            "ang_radius_c_error": error on the above
+            "ang_radius_t": maximum angular distance from the center, i.e. angular King's tidal radius of the cluster
+            "ang_radius_t_error": error on the above
+
+            # Parsec radii
+            "radius_50": median distance from the center, i.e.radius of the cluster with 50% of members
+            "radius_50_error": error on the above
+            "radius_c": King's core radius of the cluster
+            "radius_c_error": error on the above
+            "radius_t": maximum distance from the center, i.e. King's tidal radius of the cluster
+            "radius_t_error": error on the above
+            }
+
+    """
+    inferred_parameters = {}
+    sqrt_n_stars = np.sqrt(data_gaia.shape[0])
+
+    # Grab the distances if they aren't specified - we'll need them in a moment!
+    if already_inferred_parameters is None:
+        already_inferred_parameters = mean_distance(data_gaia, membership_probabilities)
+
+    # Estimate the ra, dec of the cluster as the weighted mean
+    ra_data = _handle_ra_discontinuity(
+        data_gaia[key_ra], middle_ras_raise_error=middle_ras_raise_error
+    )
+
+    inferred_parameters["ra"] = np.average(ra_data, weights=membership_probabilities)
+    inferred_parameters["ra_std"] = _weighted_standard_deviation(
+        ra_data, membership_probabilities
+    )
+    inferred_parameters["ra_error"] = inferred_parameters["ra_std"] / sqrt_n_stars
+
+    if inferred_parameters["ra"] < 0:
+        inferred_parameters["ra"] += 360
+
+    inferred_parameters["dec"] = np.average(
+        data_gaia[key_dec], weights=membership_probabilities
+    )
+    inferred_parameters["dec_std"] = _weighted_standard_deviation(
+        data_gaia[key_dec], membership_probabilities
+    )
+    inferred_parameters["dec_error"] = inferred_parameters["dec_std"] / sqrt_n_stars
+
+    inferred_parameters["ang_dispersion"] = np.sqrt(
+        inferred_parameters["ra_std"] ** 2 + inferred_parameters["dec_std"] ** 2
+    )
+
+    # Calculate how far every star in the cluster is from the central point
+    center_skycoord = SkyCoord(
+        ra=inferred_parameters["ra"], dec=inferred_parameters["dec"], unit="deg"
+    )
+    star_skycoords = SkyCoord(
+        ra=data_gaia[key_ra].to_numpy(), dec=data_gaia[key_dec].to_numpy(), unit="deg"
+    )
+
+    distances_from_center = center_skycoord.separation(star_skycoords).degree
+
+    # And say something about the radii in this case
+    inferred_parameters["ang_radius_50"] = np.median(distances_from_center)
+    inferred_parameters["ang_radius_50_error"] = np.nan
+
+    inferred_parameters["ang_radius_c"] = np.nan
+    inferred_parameters["ang_radius_c_error"] = np.nan
+
+    inferred_parameters["ang_radius_t"] = np.max(distances_from_center)
+    inferred_parameters["ang_radius_t_error"] = np.nan
+
+    # Convert the angular distances into parsecs
+    inferred_parameters["radius_50"] = (
+        np.tan(inferred_parameters["ang_radius_50"] * deg_to_rad)
+        * already_inferred_parameters[distance_to_use]
+    )
+    inferred_parameters["radius_50_error"] = np.nan
+    inferred_parameters["radius_c"] = np.nan
+    inferred_parameters["radius_c_error"] = np.nan
+    inferred_parameters["radius_t"] = (
+        np.tan(inferred_parameters["ang_radius_t"] * deg_to_rad)
+        * already_inferred_parameters[distance_to_use]
+    )
+    inferred_parameters["radius_t_error"] = np.nan
+
+    return inferred_parameters
+
+
+def all_statistics():
+    """
+    """
+    # Todo refactor this (and other high-level calculation methods)
+    pass

ocelot-0.3.1a0/src/ocelot/calculate/distance.py

@@ -0,0 +1 @@
+"""Functions for working with cluster distances."""

ocelot-0.3.1a0/src/ocelot/calculate/generic.py

@@ -0,0 +1,97 @@
+"""Generic calculation utilities used across the module."""
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+from typing import Optional, Union
+from ocelot.util.check import _check_matching_lengths_of_non_nones
+from scipy.stats import directional_stats
+
+
+def _weighted_standard_deviation(x: ArrayLike, weights: Optional[ArrayLike] = None):
+    """Computes weighted standard deviation. Uses method from
+    https://stackoverflow.com/a/52655244/12709989.
+    """
+    # Todo: not sure that this deals with small numbers of points correctly!
+    #   See: unit test fails when v. few points used
+    return np.sqrt(np.cov(x, aweights=weights))
+
+
+def standard_error(
+    standard_deviation: Union[ArrayLike[Union[float, int]], float, int],
+    number_of_measurements: Union[ArrayLike[int], int],
+) -> float:
+    """Calculates the standard error on the mean of some parameter given the standard
+    deviation.
+
+    Parameters
+    ----------
+    standard_deviation : array-like, float, or int
+        Standard deviation(s)
+    number_of_measurements : array-like of ints, int
+        Number of measurements used to find standard deviation.
+
+    Returns
+    -------
+    standard_error : float
+    """
+    return standard_deviation / np.sqrt(number_of_measurements)
+
+
+def mean_and_deviation(
+    values: ArrayLike,
+    weights: Optional[ArrayLike] = None,
+) -> tuple[float]:
+    """Calculates the mean and standard deviation of some set of values.
+
+    Parameters
+    ----------
+    values : array-like
+        Values to calculate mean and standard deviation of.
+    weights : array-like, optional
+        Array of weights to use to compute a weighted mean and average.
+
+    Returns
+    -------
+    mean : float
+        Mean of values.
+    std : float
+        Standard deviation of values.
+    """
+    _check_matching_lengths_of_non_nones(values, weights)
+
+    return (
+        np.average(values, weights=weights),
+        _weighted_standard_deviation(values, weights),
+    )
+
+
+def lonlat_to_unitvec(longitudes: NDArray, latitudes: NDArray):
+    """Converts longitudes and latitudes to unit vectors on a unit sphere. Uses method 
+    at https://en.wikipedia.org/wiki/Spherical_coordinate_system#Cartesian_coordinates.
+    Assumes that latitudes is in the range [-pi / 2, pi / 2] as is common in 
+    astronomical unit systems.
+    """
+    x = np.cos(latitudes) * np.cos(longitudes)
+    y = np.cos(latitudes) * np.sin(longitudes)
+    z = np.sin(latitudes)
+    return np.column_stack((x, y, z))
+
+
+def unitvec_to_lonlat(unit_vectors: NDArray):
+    """Converts unit vectors on a unit sphere to longitudes and latitudes. See 
+    `lonlat_to_unitvec` for more details.
+    """
+    x, y, z = [column.ravel() for column in np.hsplit(unit_vectors, 3)]
+    longitudes = np.arctan2(y, x)
+    latitudes  = np.arcsin(z / np.sqrt(x**2 + y**2 + z**2))
+    return longitudes, latitudes
+
+
+def spherical_mean(longitudes: ArrayLike, latitudes: ArrayLike):
+    """Calculates the spherical mean of angular positions."""
+    longitudes = np.asarray_chkfinite(longitudes)
+    latitudes = np.asarray_chkfinite(latitudes)
+
+    unit_vectors = lonlat_to_unitvec(longitudes, latitudes)
+    mean_unit_vector = directional_stats(unit_vectors).mean_direction
+    mean_lon, mean_lat = unitvec_to_lonlat(mean_unit_vector)
+    return mean_lon[0], mean_lat[0]

ocelot-0.3.1a0/src/ocelot/calculate/motion.py

@@ -0,0 +1,11 @@
+"""Tools for calculating values based on proper motions and/or velocities."""
+
+
+def radial_velocity(velocities, with_frame_correction=False):
+    # Todo
+    pass
+
+
+def proper_motion(proper_motions, with_frame_correction=False):
+    # Todo
+    pass

ocelot-0.3.1a0/src/ocelot/calculate/position.py

@@ -0,0 +1,64 @@
+"""Different methods for calculating the center of a cluster in spherical coordinates. 
+(This is actually oddly difficult, thanks to how spheres work. Damn spheres.)
+"""
+import numpy as np
+from numpy.typing import ArrayLike
+
+from ocelot.calculate.generic import spherical_mean
+
+
+def mean_position(
+    longitudes: ArrayLike, latitudes: ArrayLike, degrees=True
+) -> tuple[float]:
+    """Calculates the spherical mean of angular positions, specified as longitudes and
+    latitudes. This uses directional statistics to do so in a way that is aware of
+    discontinuities, such as the fact that 0° = 360°.
+
+    Parameters
+    ----------
+    longitudes : array-like
+        Array of longitudinal positions of stars in your cluster (e.g. right ascensions
+        or galactic longitudes.) Assumed to be in the range [0°, 360°].
+    latitudes : array-like
+        Array of latitudinal positions of stars in your cluster (e.g. declinations or 
+        galactic latitudes.) Assumed to be in the range [-90°, 90°].
+    degrees : bool
+        Whether longitudes and latitudes are in degrees, and whether to return an answer
+        in degrees. Defaults to True. If False, longitudes and latitudes are assumed to
+        be in radians, with ranges [0, 2π] and [-π/2, π/2] respectively.
+
+    Returns
+    -------
+    mean_longitude : float
+    mean_latitude : float
+
+    Notes
+    -----
+    This function explicitly assumes that your star cluster *has* a well-defined mean
+    position. Some configurations (such as points uniformly distributed in at least one
+    axis of a sphere) will not have a meaningful mean position.
+
+    Internally, this function uses `scipy.stats.directional_stats`, with a definition
+    taken from [1]. See [2] for more background.
+
+    References
+    ----------
+    [1] Mardia, Jupp. (2000). Directional Statistics (p. 163). Wiley.
+    [2] https://en.wikipedia.org/wiki/Directional_statistics
+    """
+    if degrees:
+        longitudes, latitudes = np.radians(longitudes), np.radians(latitudes)
+    mean_lon, mean_lat = spherical_mean(longitudes, latitudes)
+    if degrees:
+        return np.degrees(mean_lon), np.degrees(mean_lat)
+    return mean_lon, mean_lat
+
+
+def mode_position():
+    """Attempts to find the mode of a star cluster's 2D on-sky distribution. This is a 
+    better estimator than the mean position for clusters that are assymmetric, which is
+    often the case for clusters with assymetric tidal tails (e.g. due to one side being
+    more easily detected than the other.)
+    """
+    # Todo
+    pass