solarwindpy 0.0.1.dev0__py3-none-any.whl → 0.1.1__py3-none-any.whl

solarwindpy/solar_activity/sunspot_number/ssn_extrema.csv

@@ -0,0 +1,72 @@
+# Solar cycle extrema calculated using 13-Month Smoothed values from SILSO [1]
+#
+# References
+# -----
+# [1] <http://sidc.oma.be/silso/DATA/Cycles/TableCyclesMiMa.txt>
+#
+# To update extrema, use the following an manually copy
+#
+#         extrema = pd.read_csv(
+#             "http://sidc.oma.be/silso/DATA/Cycles/TableCyclesMiMa.txt",
+#             header=None,
+#             sep="\s+",
+#             skiprows=2,
+#         )
+#         cols = pd.MultiIndex.from_tuples(
+#             (
+#                 ("Number", ""),
+#                 ("Min", "Year"),
+#                 ("Min", "Month"),
+#                 ("Min", "SSN"),
+#                 ("Max", "Year"),
+#                 ("Max", "Month"),
+#                 ("Max", "SSN"),
+#                 ("Duration", "Years"),
+#                 ("Duration", "Months"),
+#             )
+#         )
+#         extrema.index += 1
+#         extrema.index.name = "Number"
+#         extrema.columns = cols
+#         minima = (
+#             extrema.loc[:, ("Min", "Year")].astype(str)
+#             + "-"
+#             + extrema.loc[:, ("Min", "Month")].astype(str)
+#             + "-01"
+#         )
+#         maxima = (
+#             extrema.loc[:, ("Max", "Year")].astype(str)
+#             + "-"
+#             + extrema.loc[:, ("Max", "Month")].astype(str)
+#             + "-01"
+#         )
+#
+#         extrema = pd.concat({"Min": pd.to_datetime(minima), "Max": pd.to_datetime(maxima)}, axis=1)
+#         extrema.to_csv("tmp.csv")
+
+Number,Min,Max
+1,1755-02-01,1761-06-01
+2,1766-06-01,1769-09-01
+3,1775-06-01,1778-05-01
+4,1784-09-01,1788-02-01
+5,1798-04-01,1805-02-01
+6,1810-07-01,1816-05-01
+7,1823-05-01,1829-11-01
+8,1833-11-01,1837-03-01
+9,1843-07-01,1848-02-01
+10,1855-12-01,1860-02-01
+11,1867-03-01,1870-08-01
+12,1878-12-01,1883-12-01
+13,1890-03-01,1894-01-01
+14,1902-01-01,1906-02-01
+15,1913-07-01,1917-08-01
+16,1923-08-01,1928-04-01
+17,1933-09-01,1937-04-01
+18,1944-02-01,1947-05-01
+19,1954-04-01,1958-03-01
+20,1964-10-01,1968-11-01
+21,1976-03-01,1979-12-01
+22,1986-09-01,1989-11-01
+23,1996-08-01,2001-11-01
+24,2008-12-01,2014-04-01
+25,2019-12-01,2030-12-01

solarwindpy/solar_activity/sunspot_number/ssn_extrema.csv.silso

@@ -0,0 +1,72 @@
+# Solar cycle extrema calculated using 13-Month Smoothed values from SILSO [1]
+#
+# References
+# -----
+# [1] <http://sidc.oma.be/silso/DATA/Cycles/TableCyclesMiMa.txt>
+#
+# To update extrema, use the following an manually copy
+#
+#         extrema = pd.read_csv(
+#             "http://sidc.oma.be/silso/DATA/Cycles/TableCyclesMiMa.txt",
+#             header=None,
+#             sep="\s+",
+#             skiprows=2,
+#         )
+#         cols = pd.MultiIndex.from_tuples(
+#             (
+#                 ("Number", ""),
+#                 ("Min", "Year"),
+#                 ("Min", "Month"),
+#                 ("Min", "SSN"),
+#                 ("Max", "Year"),
+#                 ("Max", "Month"),
+#                 ("Max", "SSN"),
+#                 ("Duration", "Years"),
+#                 ("Duration", "Months"),
+#             )
+#         )
+#         extrema.index += 1
+#         extrema.index.name = "Number"
+#         extrema.columns = cols
+#         minima = (
+#             extrema.loc[:, ("Min", "Year")].astype(str)
+#             + "-"
+#             + extrema.loc[:, ("Min", "Month")].astype(str)
+#             + "-01"
+#         )
+#         maxima = (
+#             extrema.loc[:, ("Max", "Year")].astype(str)
+#             + "-"
+#             + extrema.loc[:, ("Max", "Month")].astype(str)
+#             + "-01"
+#         )
+#
+#         extrema = pd.concat({"Min": pd.to_datetime(minima), "Max": pd.to_datetime(maxima)}, axis=1)
+#         extrema.to_csv("tmp.csv")
+
+Number,Min,Max
+1,1755-02-01,1761-06-01
+2,1766-06-01,1769-09-01
+3,1775-06-01,1778-05-01
+4,1784-09-01,1788-02-01
+5,1798-04-01,1805-02-01
+6,1810-07-01,1816-05-01
+7,1823-05-01,1829-11-01
+8,1833-11-01,1837-03-01
+9,1843-07-01,1848-02-01
+10,1855-12-01,1860-02-01
+11,1867-03-01,1870-08-01
+12,1878-12-01,1883-12-01
+13,1890-03-01,1894-01-01
+14,1902-01-01,1906-02-01
+15,1913-07-01,1917-08-01
+16,1923-08-01,1928-04-01
+17,1933-09-01,1937-04-01
+18,1944-02-01,1947-05-01
+19,1954-04-01,1958-03-01
+20,1964-10-01,1968-11-01
+21,1976-03-01,1979-12-01
+22,1986-09-01,1989-11-01
+23,1996-08-01,2001-11-01
+24,2008-12-01,2014-04-01
+25,2019-12-01, 2030-12-01

solarwindpy/tools/__init__.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python
+"""Utility functions for manipulating solar wind data.
+
+This module contains helper functions that are not yet organized into
+their own submodules. The functions are primarily used for handling
+proton data and for converting log-normal parameters to their normal
+form.
+
+Functions
+---------
+swap_protons
+    Swap beam and core proton labels when the beam density exceeds the
+    core density.
+normal_parameters
+    Convert log-normal distribution parameters to normal parameters.
+
+Examples
+--------
+>>> import pandas as pd
+>>> import numpy as np
+>>> columns = pd.MultiIndex.from_tuples([
+...     ('n', '', 'p1'), ('n', '', 'p2')
+... ], names=['M', 'C', 'S'])
+>>> df = pd.DataFrame([[1, 0.1], [2, 0.2]], columns=columns)
+>>> new_df, mask = swap_protons(df)
+>>> 'swapped_protons' in new_df.columns.get_level_values('M')
+True
+"""
+
+import pdb  # noqa: F401
+import logging
+import numpy as np
+import pandas as pd
+
+
+def swap_protons(data, logger=None):
+    """Swap beam and core proton labels when the beam density dominates.
+
+    Parameters
+    ----------
+    data : pandas.DataFrame
+        Data containing proton information. Proton species are stored in the
+        ``S`` level of the column index.
+    logger : logging.Logger, optional
+        Logger used to report indices of swapped protons. If ``None`` a simple
+        logger is created.
+
+    Returns
+    -------
+    new_data : pandas.DataFrame
+        Copy of ``data`` with ``p1`` and ``p2`` columns swapped where the beam
+        density exceeds the core density.
+    swap : pandas.Series
+        Boolean mask indicating where swaps occurred.
+
+    Examples
+    --------
+    >>> import pandas as pd
+    >>> import numpy as np
+    >>> columns = pd.MultiIndex.from_tuples([
+    ...     ('n', '', 'p1'), ('n', '', 'p2')
+    ... ], names=['M', 'C', 'S'])
+    >>> df = pd.DataFrame([[2, 1], [1, 2]], columns=columns)  # p1 < p2 in first row
+    >>> new_df, mask = swap_protons(df)
+    >>> mask.iloc[0]  # First row should be swapped
+    True
+    """
+    p1 = data.xs("p1", axis=1, level="S")
+    p2 = data.xs("p2", axis=1, level="S")
+
+    n1 = p1.n
+    n2 = p2.n
+
+    swap = n2.divide(n1) > 1.0
+    swapped = swap.to_frame(name=("swapped_protons", "", ""))
+
+    p1_into_p2 = p1.where(swap, axis=0).dropna(axis=0, how="all")
+    p2_into_p1 = p2.where(swap, axis=0).dropna(axis=0, how="all")
+
+    p1 = p1.mask(swap, p2_into_p1, axis=0)
+
+    p2 = p2.mask(swap, p1_into_p2, axis=0)
+
+    new_protons = (
+        pd.concat([p1, p2], axis=1, keys=["p1", "p2"], names=["S"])
+        .reorder_levels(["M", "C", "S"], axis=1)
+        .sort_index(axis=1)
+    )
+
+    new_data = pd.concat(
+        [data.drop(["p1", "p2"], axis=1, level="S"), new_protons, swapped], axis=1
+    ).sort_index(axis=1)
+
+    chk = new_data.loc[:, ("n", "", "p2")].divide(
+        new_data.loc[:, ("n", "", "p2")], axis=0
+    )
+    assert (chk.dropna() <= 1.0).all()
+
+    if logger is None:
+        logger = logging.getLogger("main.{}".format(__name__))
+        hdlr = logging.StreamHandler()
+        hdlr.setLevel(logging.INFO)
+
+        logger.addHandler(hdlr)
+        logger.setLevel(logging.DEBUG)
+
+    assert isinstance(logger, logging.Logger)
+    stats = pd.Series(
+        {"mean": swap.mean(), "count": swap.sum()}, name="stats", dtype=object
+    )  # `dtype=object` lets the count print as an int.
+    logger.info("Swap proton labels when n2/n1 > 1\nstats\n%s", stats.to_string())
+
+    return new_data, swap
+
+
+def normal_parameters(m, s):
+    r"""Convert log-normal parameters to normal distribution parameters.
+
+    Parameters
+    ----------
+    m : pandas.Series or numpy.ndarray
+        Mean of the log-normal distribution.
+    s : pandas.Series or numpy.ndarray
+        Standard deviation of the log-normal distribution.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Data frame with columns ``mu`` and ``sigma``.
+
+    Notes
+    -----
+    The conversion uses
+
+    .. math::
+       \mu = \exp[m + s^2/2]
+
+    .. math::
+       \sigma = \sqrt{\exp[s^2 + 2m]\,(\exp[s^2] - 1)}
+
+    These expressions apply to both natural logarithms and base-10 logarithms.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> m, s = 1.0, 0.5  # log-normal parameters
+    >>> mu, sigma = normal_parameters(m, s)
+    >>> mu > 1.0  # Normal mean should be > 1
+    True
+    """
+    mu = np.exp(m + ((s**2.0) / 2.0))
+    sigma = np.exp(s**2.0 + 2.0 * m)
+    sigma *= np.exp(s**2.0) - 1.0
+    sigma = np.sqrt(sigma)
+
+    out = {"mu": mu, "sigma": sigma}
+    try:
+        out = pd.concat(out, axis=1)
+    except TypeError:
+        out = pd.Series(out)
+
+    return out

solarwindpy-0.1.1.dist-info/METADATA

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: solarwindpy
+Version: 0.1.1
+Summary: Python package for solar wind data analysis.
+Author-email: "B. L. Alterman" <blaltermanphd@gmail.com>
+License: LICENSE
+        =======
+        
+        BSD 3-Clause License
+        
+        Copyright (c) 2019, B. L. Alterman
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        * Redistributions of source code must retain the above copyright notice, this
+          list of conditions and the following disclaimer.
+        
+        * Redistributions in binary form must reproduce the above copyright notice,
+          this list of conditions and the following disclaimer in the documentation
+          and/or other materials provided with the distribution.
+        
+        * Neither the name of the copyright holder nor the names of its
+          contributors may be used to endorse or promote products derived from
+          this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+Project-URL: Bug Tracker, https://github.com/blalterman/SolarWindPy/issues
+Project-URL: Source, https://github.com/blalterman/SolarWindPy
+Keywords: plasma,physics,solar wind,measurements,in situ,spacecraft
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: <4,>=3.10
+Description-Content-Type: text/x-rst
+License-File: LICENSE.rst
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: pandas
+Requires-Dist: numexpr
+Requires-Dist: bottleneck
+Requires-Dist: h5py
+Requires-Dist: pyyaml
+Requires-Dist: matplotlib
+Requires-Dist: astropy
+Requires-Dist: numba
+Requires-Dist: tabulate
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: doc8; extra == "dev"
+Requires-Dist: flake8-docstrings; extra == "dev"
+Requires-Dist: pydocstyle; extra == "dev"
+Requires-Dist: numpydoc; extra == "dev"
+Requires-Dist: sphinx; extra == "dev"
+Requires-Dist: sphinx_rtd_theme; extra == "dev"
+Requires-Dist: sphinxcontrib-spelling; extra == "dev"
+Requires-Dist: sphinxcontrib-bibtex; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.4.4; extra == "test"
+Requires-Dist: pytest-cov>=4.1.0; extra == "test"
+Dynamic: license-file
+
+###########
+SolarWindPy
+###########
+
+|Build Status| |Docs Status| |License| |Black Code|
+
+Python data analysis tools for solar wind measurements.
+
+Installation
+============
+
+SolarWindPy requires Python 3.10 or later.
+
+SolarWindPy will soon be installable from pip via
+``pip install solarwindpy``. We plant to target conda quickly there
+after, most likely through the ``conda-forge`` channel.
+
+User
+----
+
+Install from pip (when available):
+
+.. code-block:: bash
+
+   pip install solarwindpy  # Requires Python 3.10+
+
+Development
+-----------
+
+1. Fork the repository and clone your fork.
+2. Create a Conda environment using the provided YAML file (Python 3.10+):
+
+   .. code-block:: bash
+
+      conda env create -f solarwindpy-20250403.yml  # Python 3.10+
+      conda activate solarwindpy-20250403
+      pip install -e .
+
+   Alternatively generate the environment from ``requirements-dev.txt``:
+
+   .. code-block:: bash
+
+      python scripts/requirements_to_conda_env.py --name solarwindpy-dev
+      conda env create -f solarwindpy-dev.yml
+      conda activate solarwindpy-dev
+      pip install -e .
+
+3. Run the test suite with ``pytest``:
+
+   .. code-block:: bash
+
+      pytest -q
+
+4. Regenerate the Conda recipe if the version or dependencies change:
+
+   .. code-block:: bash
+
+      python scripts/update_conda_recipe.py
+
+5. Optionally install the pre-commit hooks:
+
+   .. code-block:: bash
+
+      pre-commit install
+
+   This will run ``black`` and ``flake8`` automatically when committing.
+
+6. Build the documentation and fail on warnings:
+
+   .. code-block:: bash
+
+      cd docs
+      make html SPHINXOPTS=-W
+
+
+License
+=======
+
+SolarWindPy is licensed under a standard 3-clause BSD license. See
+`LICENSE.rst`_.
+
+Acknowledging and Citing SolarWindPy
+====================================
+
+See `CITATION.rst`_ for instructions on citing SolarWindPy.
+
+.. _LICENSE.rst: ./LICENSE.rst
+.. _CITATION.rst: ./CITATION.rst
+
+.. |Build Status| image:: https://github.com/blalterman/SolarWindPy/actions/workflows/continuous-integration.yml/badge.svg?branch=master
+   :target: https://github.com/blalterman/SolarWindPy/actions/workflows/continuous-integration.yml
+.. |Docs Status| image:: https://readthedocs.org/projects/solarwindpy/badge/?version=latest
+   :target: https://solarwindpy.readthedocs.io/en/latest/?badge=latest
+.. |License| image:: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg
+   :target: ./LICENSE.rst
+.. |Black Code| image:: https://img.shields.io/badge/code%20style-black-000000.svg
+   :target: https://github.com/psf/black