Merge pull request #50 from MDAnalysis/pyedr

Create the pyedr and panedr packages

Author: jbarnoud

.coveragerc

@@ -1,7 +1,6 @@
 [run]
 omit =
-    panedr/*
-    tests/data/*
+    pyedr/pyedr/tests/data/*
 
 [report]
 exclude_lines =

.github/workflows/deploy.yaml

@@ -0,0 +1,69 @@
+name: Build and upload to PyPI
+
+on:
+  pull_request:
+    branches:
+      - "package-*"
+  push:
+    branches:
+      - "package-*"
+    tags:
+      - "package-*"
+  release:
+    types:
+      - published
+
+
+concurrency:
+  group: "${{ github.ref }}-${{ github.head_ref }}-${{ github.workflow }}"
+  cancel-in-progress: true
+
+
+defaults:
+  run:
+    shell: bash -l {0}
+
+
+jobs:
+  build_wheels:
+    environment: deploy
+    if: "github.repository == 'MDAnalysis/panedr'"
+    name: Build pure Python wheel
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: setup_miniconda
+        uses: conda-incubator/setup-miniconda@v2
+        with:
+          python-version: 3.8
+          auto-update-conda: true
+          add-pip-as-python-dependency: true
+          architecture: x64
+
+      - name: install_deps
+        run: |
+          cd pyedr && python -m pip install build
+          cd panedr && python -m pip install build
+
+      - name: build
+        run: |
+          cd pyedr && python -m build --sdist --wheel --outdir ../dist/
+          cd panedr && python -m build --sdist --wheel --outdir ../dist
+
+      - name: publish_testpypi
+        # Upload to testpypi on every tag
+        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+        uses: pypa/gh-action-pypi-publish@master
+        with:
+          password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+          repository_url: https://test.pypi.org/legacy/
+
+      - name: publish_pypi
+        if: github.event_name == 'release' && github.event.action == 'published'
+        uses: pypa/gh-action-pypi-publish@master
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

.github/workflows/gh-ci.yaml

@@ -45,7 +45,7 @@ jobs:
 
     - name: install package deps
       run: |
-        mamba install pandas pytest pytest-xdist pytest-cov codecov pbr
+        mamba install pytest pytest-xdist pytest-cov codecov pbr numpy
 
     - name: check install
       run: |
@@ -54,28 +54,32 @@ jobs:
         conda info
         conda list
 
-    - name: install panedrlite package
+    - name: install pyedr package
       run: |
         # installing via pip leads to codecov not being able to report coverage
-        cd panedrlite && python setup.py develop
+        cd pyedr && python setup.py develop
+
+    - name: run pyedr tests
+      run: |
+        pytest -n 2 -v --cov=pyedr/pyedr --cov-report=xml --color=yes pyedr/pyedr/tests
 
     - name: install panedr package
       run: |
+        mamba install pandas
         cd panedr && python setup.py develop
 
+    - name: run panedr tests
+      run: |
+        pytest -n2 -v --cov=panedr/panedr --cov-report=xml --color=yes --cov-append panedr/panedr/tests
+
     - name: test imports
       # Exit the git repo in order for pbr to stop auto-picking up version info
       # from the local git data
       working-directory: ../
       run: |
-        python -Ic "from panedrlite import edr_to_dict"
+        python -Ic "from pyedr import edr_to_dict"
         python -Ic "from panedr import edr_to_df"
 
-
-    - name: run unit tests
-      run: |
-        pytest -n 2 -v --cov=panedrlite/panedrlite --cov-report=xml --color=yes ./tests
-
     - name: codecov
       uses: codecov/codecov-action@v3
       with:

MANIFEST.in

@@ -1,113 +1,131 @@
-Panedr
-======
+Pyedr and Panedr
+================
 
 |Build Status| |cov|
 
-Panedr reads a `Gromacs EDR`_ binary energy XDR file and returns its content
-as a pandas_ dataframe. The library exposes three functions:
+This repository hosts the source files for both the Pyedr and Panedr packages.
 
-- the ``edr_to_df`` function, which gets the path to an EDR file and returns a
-  pandas DataFrame,
+``pyedr`` and ``panedr`` are compatible with Python 3.6 and greater.
+
+Pyedr
+-----
+
+Pyedr provides a means of reading a `Gromacs EDR`_ binary XDR file and
+return its contents as a dictionary of `numpy`_ arrays. Pyedr exposes
+the following functions:
 
-- the ``edr_to_dict`` function, which returns a dictionary of NumPy arrays instead
-  of a pandas DataFrame
+- ``edr_to_dict``: returns a dictionary of NumPy arrays keyed by the energy
+  type from a given path to an EDR file.
+- ``read_edr``: parses an EDR file and returns the energy terms
+  in a nested list
 
-- and the ``read_edr`` function, which is called by the other two functions to
-  do the actual reading of EDR files. It returns a tuple of lists.
 
-``panedr`` is compatible with Python 3.6 and greater.
+Panedr
+------
+
+Panedr uses the Pyedr library to read a `Gromacs EDR`_ binary energy XDR file
+and returns its contents as a pandas_ dataframe. Panedr exposes the
+following function:
+
+- ``edr_to_df``: which gets the path to an EDR file and returns a
+  pandas DataFrame,
+
 
 Example
 -------
 
+Using ``pyedr``:
+
+
+.. code:: python
+
+    import pyedr
+
+    # Read the EDR file
+    path = 'ener.edr'
+    dic = pyedr.edr_to_dict(path)
+
+    # The `verbose` optional parameter can be set to True to display the
+    # progress on stderr
+    dic = pyedr.edr_to_dict(path, verbose=True)
+
+    # Get the average pressure after the first 10 ns
+    pressure_avg = dic['Pressure'][dic['Time'] > 10000].mean()
+
+
+Using ``panedr``:
+
+
 .. code:: python
 
     import panedr
 
     # Read the EDR file
     path = 'ener.edr'
     df = panedr.edr_to_df(path)
-    dic = panedr.edr_to_dict(path)
 
     # The `verbose` optional parameter can be set to True to display the
     # progress on stderr
     df = panedr.edr_to_df(path, verbose=True)
-    dic = panedr.edr_to_dict(path, verbose=True)
 
     # Get the average pressure after the first 10 ns
     pressure_avg = df['Pressure'][df['Time'] > 10000].mean()
-    pressure_avg = dic['Pressure'][dic['Time'] > 10000].mean()
 
 
 Install
 -------
-Install panedr ``pip``:
+
+You can install ``pyedr`` and ``panedr`` using ``pip``:
 
 .. code:: bash
 
+    pip install pyedr 
+
+    # installing panedr automatically installs pyedr
     pip install panedr
 
 
-If you are using `conda`_ and `conda-forge`_, you can install with
+If you are using `conda`_ and `conda-forge`_, you can install with:
 
 .. code:: bash
 
+    conda install -c conda-forge pyedr
+
+    # install panedr automatically installs pyedr
     conda install -c conda-forge panedr
 
+
 Tests
 -----
 
-The ``panedr`` repository contains a series of tests. If you downloaded or
-cloned the code from the repository, you can run the tests. To do so,
-install `pytest`_, and, in the directory of the
+The ``pyedr`` and ``panedr`` repositories contains a series of tests.
+If you downloaded or cloned the code from the repository, you can run
+the tests. To do so, install `pytest`_, and, in the directory of the
 panedr source code, run:
 
+For ``pyedr``:
+
+
 .. code:: bash
 
-    pytest -v tests
+    pytest -v pyedr/pyedr/tests
 
 
-panedrlite
-----------
-Under the hood, panedr is just a metapackage that installs panedrlite and
-the requirements for all functions, notably including pandas. To avoid requiring
-pandas in downstream applications, panedrlite is available for installation as
-well. It provides all functionality, except that pandas is not automatically
-installed as a dependency, and therefore :func:`edr_to_df` will not work
-out-of-the-box unless it is installed manually. `panedrlite` also uses the panedr
-namespace, so `import panedr` works. 
+For ``panedr``:
 
 
 .. code:: bash
 
-    pip install panedrlite
+    pytest -v panedr/panedr/tests
 
 
 License
 -------
 
-Panedr translate in python part of the source code of Gromacs.
+Pyedr and Panedr translate part of the source code of Gromacs into Python.
 Therefore, Panedr is distributed under the same GNU Lesser General
-Public License version 2.1 as Gromacs.
-
-    Panedr — a library to manipulate Gromacs EDR file in python
-
-    Copyright (C) 2016 Jonathan Barnoud
-
-    This library is free software; you can redistribute it and/or modify
-    it under the terms of the GNU Lesser General Public License as
-    published by the Free Software Foundation; either version 2.1 of the
-    License, or (at your option) any later version.
-
-    This library is distributed in the hope that it will be useful, but
-    WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-    Lesser General Public License for more details.
+Public License version 2.1 as Gromacs. See the `license`_ for more details.
 
-    You should have received a copy of the GNU Lesser General Public
-    License along with this library; if not, write to the Free Software
-    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
-    02110-1301 USA
 
 .. |Build Status| image:: https://github.com/MDAnalysis/panedr/actions/workflows/gh-ci.yaml/badge.svg
    :alt: Github Actions Build Status
@@ -118,7 +136,9 @@ Public License version 2.1 as Gromacs.
    :target: https://codecov.io/gh/MDAnalysis/panedr
 
 .. _`Gromacs EDR`: https://manual.gromacs.org/documentation/current/reference-manual/file-formats.html#edr
+.. _numpy: https://numpy.org/
 .. _pandas: https://pandas.pydata.org/
 .. _conda: https://docs.conda.io
 .. _`conda-forge`: https://conda-forge.org/
 .. _pytest: https://docs.pytest.org/
+.. _license: https://github.com/MDAnalysis/panedr/blob/master/LICENSE.txt

README.rst

@@ -0,0 +1,2 @@
+include ../README.rst ../LICENSE.txt
+include setup.py setup.cfg

panedr/MANIFEST.in

@@ -4,4 +4,4 @@
 __version__ = pbr.version.VersionInfo('panedr').release_string()
 del pbr
 
-from panedrlite import edr_to_dict, edr_to_df, read_edr
+from .panedr import edr_to_df

panedr/panedr/__init__.py

@@ -0,0 +1,65 @@
+#-*- coding:utf-8 -*-
+# Panedr -- a library to manipulate Gromacs EDR file in python
+# Copyright (C) 2016  Jonathan Barnoud
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor,
+# Boston, MA  02110-1301  USA
+
+# Most of this file is a python rewrite of part of
+# `src/gromacs/fileio/enxio.c` from Gromacs 5.1.
+# See gromacs.org.
+
+"""
+Panedr -- Read Gromacs energy file (EDR) to ``pandas.Dataframe`` in python
+==========================================================================
+
+The ``panedr`` library allows users to read and manipulate the content of
+Gromacs energy file (.edr files) in python using pandas Dataframes.
+
+This uses the ``pyedr`` library which tries to be in par with Gromacs 5.1.1
+when it comes to reading EDR files.
+
+So far, only one function is exposed by the library : the :fun:`edr_to_df`
+function that returns a pandas ``DataFrame`` from an EDR file.
+
+.. autofunction:: edr_to_df
+"""
+
+from pyedr import edr_to_dict, read_edr
+import pandas as pd
+
+
+__all__ = ['edr_to_df', ]
+
+
+def edr_to_df(path: str, verbose: bool = False) -> pd.DataFrame:
+    """Calls :func:`read_edr` from ``pyedr`` and packs its return values into
+    a ``pandas.DataFrame``.
+
+    Parameters
+    ----------
+    path : str
+        path to EDR file to be read
+    verbose : bool
+        Optionally show verbose output while reading the file
+    Returns
+    -------
+    df: pandas.DataFrame
+        :class:`pandas.DataFrame()` object that holds all energy terms found in
+        the EDR file.
+    """
+    all_energies, all_names, times = read_edr(path, verbose=verbose)
+    df = pd.DataFrame(all_energies, columns=all_names, index=times)
+    return df