refactor: improve overall repo [2] (#30)

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,24 +1,32 @@
-## Description
+## Proposed changes ⤴️
 
-Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change.
+Describe the big picture of your changes, add relevant motivation and context.
 
-Fixes # (issue)
+**If it fixes a bug or resolves a feature request, please link a corresponding issue:**
+Fixes #
 
-## Type of change
+## Types of changes 🔧
 
-Please delete options that are not relevant.
+What type of changes does your code introduce to the project?
 
-- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] Bugfix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
 - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
-- [ ] Documentation updated
+- [ ] Other
 
-## Checklist:
+## Checklist ✅
 
-- [ ] My code follows the style guidelines of this project
-- [ ] I have performed a self-review of my own code
-- [ ] I have commented my code, particularly in hard-to-understand areas
-- [ ] My changes generate no new warnings
-- [ ] I have added tests that prove my fix is effective or that my feature works
-- [ ] New and existing unit tests pass locally with my changes
-- [ ] I have not reduced the existing code coverage
+If you're unsure about any of those below, ask explicitly.
+This is simply a reminder of what needs to be checked before merging your code.
+
+- [ ] I have read the [CONTRIBUTING](https://github.com/AngryMaciek/angry-moran-simulator/blob/master/CONTRIBUTING.md).
+- [ ] I have performed a self-review of my own code.
+- [ ] Tests specified with the 'make' framework do not raise any errors.
+- [ ] I have added tests that prove my fix is effective or that my feature works.
+- [ ] I have added necessary documentation (if appropriate).
+- [ ] My changes generate no new warnings.
+- [ ] I have commented my code, particularly in hard-to-understand areas.
+
+## Further comments 🧠
+
+If this is a relatively large or complex change feel free to provide additional information or explanation.

.github/workflows/build.yml

@@ -18,10 +18,10 @@ jobs:
       - name: Checkout Repository
         uses: actions/checkout@v2
 
-      - name: Set up Python 3.9
+      - name: Set up Python 3.11
         uses: actions/setup-python@v1
         with:
-          python-version: 3.9
+          python-version: 3.11
 
       - name: Install the Package
         run: python -m pip install .
@@ -46,7 +46,7 @@ jobs:
       - name: Setup Miniconda & Environment
         uses: conda-incubator/setup-miniconda@v2
         with:
-          python-version: 3.9
+          python-version: 3.11
           auto-update-conda: true
           auto-activate-base: true
 

.github/workflows/devdocker.yml

@@ -0,0 +1,39 @@
+name: development container tests
+
+on:
+  push:
+    branches:
+      - '*'
+
+jobs:
+  devcontainer:
+    runs-on: ubuntu-22.04
+
+    steps:
+
+      - name: Check out source repository
+        uses: actions/checkout@v2
+
+      - name: Build Docker image
+        run: docker build -t moranpycess:latest -f Dockerfile .
+
+      # non-interactive shell needs to initialise & activate conda in a different way than -it
+      # ~AngryMaciek
+      - name: make help
+        run: |
+          docker run --name moranpycess -v /home/runner/work/angry-moran-simulator/angry-moran-simulator:/moranpycess moranpycess /bin/bash -c "source /mambaforge/etc/profile.d/conda.sh && conda activate moranpycess-dev && make"
+          docker rm moranpycess
+      # Dockerception is not advised (running Docker in a Docker, dind)
+      # https://stackoverflow.com/a/33003273/2340598
+      #
+      # While running the ci (github actions) we already start a container
+      # for each workflow; then above we build another container and would
+      # execute commands inside it. This is not a good practice.
+      # In the CI issues arise related to file permissions on the mounted
+      # volume (the moranpycess source code). Therefore we will only test
+      # "make help", not all commands of the Makefile.
+      # Development from the container has been tested locally and the
+      # commands are functional.
+      # By the way: I don't expect many developers would insist on contributing
+      # from a container anyway...
+      # ~AngryMaciek

.github/workflows/docs.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Setup Miniconda & Environment
         uses: conda-incubator/setup-miniconda@v2
         with:
-          python-version: 3.9
+          python-version: 3.11
           auto-update-conda: true
           activate-environment: moranpycess-dev
           environment-file: environment.yml

.github/workflows/lint.yml

@@ -17,7 +17,7 @@ jobs:
       - name: Setup Miniconda & Environment
         uses: conda-incubator/setup-miniconda@v2
         with:
-          python-version: 3.9
+          python-version: 3.11
           auto-update-conda: true
           activate-environment: moranpycess-dev
           environment-file: environment.yml

.github/workflows/publish.yml

@@ -15,10 +15,10 @@ jobs:
       - name: Checkout Repository
         uses: actions/checkout@v2
 
-      - name: Set up Python 3.9
+      - name: Set up Python 3.11
         uses: actions/setup-python@v1
         with:
-          python-version: 3.9
+          python-version: 3.11
 
       - name: Install pypa/build
         run: python -m pip install build --user

.github/workflows/unit.yml

@@ -20,7 +20,7 @@ jobs:
       - name: Setup Miniconda & Environment
         uses: conda-incubator/setup-miniconda@v2
         with:
-          python-version: 3.9
+          python-version: 3.11
           auto-update-conda: true
           activate-environment: moranpycess-dev
           environment-file: environment.yml

CITATION.cff

@@ -0,0 +1,34 @@
+cff-version: "1.2.0"
+authors:
+- family-names: Bak
+  given-names: Maciek
+  orcid: "https://orcid.org/0000-0003-1361-7301"
+- family-names: Rozlach
+  given-names: Anna M.
+  orcid: "https://orcid.org/0000-0002-5195-4299"
+doi: 10.5281/zenodo.4114143
+message: If you use this software, please cite our article in the
+  Journal of Open Source Software.
+preferred-citation:
+  authors:
+  - family-names: Bak
+    given-names: Maciek
+    orcid: "https://orcid.org/0000-0003-1361-7301"
+  - family-names: Rozlach
+    given-names: Anna M.
+    orcid: "https://orcid.org/0000-0002-5195-4299"
+  date-published: 2020-10-26
+  doi: 10.21105/joss.02643
+  issn: 2475-9066
+  issue: 54
+  journal: Journal of Open Source Software
+  publisher:
+    name: Open Journals
+  start: 2643
+  title: "Moran Pycess: a Python package to simulate Moran processes
+    driven by game theory"
+  type: article
+  url: "https://joss.theoj.org/papers/10.21105/joss.02643"
+  volume: 5
+title: "Moran Pycess: a Python package to simulate Moran processes
+  driven by game theory"

Dockerfile

@@ -1,21 +1,65 @@
+#
+# Good references:
+# https://denibertovic.com/posts/handling-permissions-with-docker-volumes/
+# https://askubuntu.com/questions/1457726/how-and-where-to-install-conda-to-be-accessible-to-all-users
+# https://www.fromlatest.io
+#
+# ~AngryMaciek
+
 ##### BASE IMAGE #####
-FROM python:3.7.4-slim
+FROM bitnami/minideb:bullseye
+# INFO: https://github.com/bitnami/minideb
 
 ##### METADATA #####
-LABEL base.image="python:3.7.4-slim"
+LABEL base.image="bitnami/minideb:bullseye"
+LABEL version="2.0.0"
 LABEL software="moranpycess"
 LABEL software.description="Python framework for Moran Processes driven by game theory"
-LABEL software.website="https://github.com/AngryMaciek/angry-moran-simulator"
 LABEL software.documentation="https://github.com/AngryMaciek/angry-moran-simulator"
-LABEL software.license="https://github.com/AngryMaciek/angry-moran-simulator/blob/master/LICENSE"
+LABEL software.website="https://github.com/AngryMaciek/angry-moran-simulator"
+LABEL software.license="MIT"
 LABEL software.tags="Bioinformatcs"
-LABEL maintainer="[email protected]"
+LABEL maintainer="Maciek Bak"
+LABEL maintainer.email="[email protected]"
+
+##### INSTALL SYSTEM-LEVEL DEPENDENCIES #####
+RUN install_packages curl ca-certificates gnupg2 git gosu
+
+##### DEFINE BUILD VARIABLES #####
+ARG MAMBADIR="/mambaforge"
+ARG CONDABINDIR="/mambaforge/bin"
+ARG MAMBAURL="https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-Linux-x86_64.sh"
+
+##### SET ENVIROMENTAL VARIABLES #####
+ENV LANG C.UTF-8
+
+##### PREPARE WORKING DIRECTORY #####
+VOLUME /moranpycess
+WORKDIR /moranpycess
+
+##### INSTALL MAMBAFORGE #####
+RUN /bin/bash -c "curl -L ${MAMBAURL} > mambaforge.sh \
+    && bash mambaforge.sh -b -p ${MAMBADIR} \
+    && ${CONDABINDIR}/conda config --system --set channel_priority strict \
+    && source ${CONDABINDIR}/activate \
+    && conda init bash \
+    && rm -f mambaforge.sh"
+
+##### BUILD DEV ENV #####
+COPY environment.yml .
+RUN /bin/bash -c "${CONDABINDIR}/mamba install conda-build boa conda-verify -c conda-forge --yes \
+  && ${CONDABINDIR}/mamba env create --file environment.yml \
+  && ${CONDABINDIR}/conda clean --all --yes \
+  && rm -f environment.yml"
 
-##### COPY REPOSITORY #####
-WORKDIR /usr/src/moranpycess
-COPY . .
+##### EXPOSE PORTS #####
+EXPOSE 8888
 
-##### INSTALL AND TEST-IMPORT #####
-RUN pip install --upgrade pip \
-  && python -m pip install . \
-  && python -c 'import moranpycess'
+##### SETUP ENTRYPOINT #####
+COPY entrypoint.sh /bin/entrypoint.sh
+RUN /bin/bash -c "chmod +x /bin/entrypoint.sh \
+  && groupadd conda \
+  && chgrp -R conda ${MAMBADIR} \
+  && chmod 770 -R ${MAMBADIR}"
+ENTRYPOINT ["/bin/entrypoint.sh"]
+CMD ["/bin/bash"]

docs/general-info/citing-contributing.rst

@@ -5,7 +5,9 @@ Citing & Contributing
 If you use Moran [Py]cess in your research **please cite the following
 article** in your paper:
 
-   Bak et al., (2020). Moran Pycess: a Python package to simulate Moran processes driven by game theory. Journal of Open Source Software, 5(54), 2643, https://doi.org/10.21105/joss.02643
+   Bak & Rozlach, (2020). Moran Pycess: a Python package to simulate Moran processes driven by game theory. Journal of Open Source Software, 5(54), 2643, https://doi.org/10.21105/joss.02643
+
+Check out our `preliminary results`_ (published in the Journal of Brief Ideas) too!
 
 This project lives off your contributions, be it in the form of bug reports,
 feature requests, discussions, or fixes and other code changes. Please refer
@@ -15,6 +17,7 @@ interactions with the community.
 
 For questions or suggestions regarding the code, please use the `issue tracker`_ at GitHub.
 
+.. _preliminary results: https://beta.briefideas.org/ideas/d292ad28e6818d20aad2286e1c9b6aa2
 .. _contributing guidelines: https://github.com/AngryMaciek/angry-moran-simulator/blob/master/CONTRIBUTING.md
 .. _code of conduct: https://github.com/AngryMaciek/angry-moran-simulator/blob/master/CODE_OF_CONDUCT.md
 .. _issue tracker: https://github.com/AngryMaciek/angry-moran-simulator/issues

docs/index.rst

@@ -90,10 +90,13 @@ and observe growth dynamics.
 If you use Moran [Py]cess in your research **please cite the following
 article** in your paper:
 
-   Bak et al., (2020). Moran Pycess: a Python package to simulate Moran processes driven by game theory. Journal of Open Source Software, 5(54), 2643, https://doi.org/10.21105/joss.02643
+   Bak & Rozlach, (2020). Moran Pycess: a Python package to simulate Moran processes driven by game theory. Journal of Open Source Software, 5(54), 2643, https://doi.org/10.21105/joss.02643
+
+Check out our `preliminary results`_ (published in the Journal of Brief Ideas) too!
 
 Feel free to inspect the code behind our work at the `official GitHub repository`_.
 
 Build date: |today|, Latest version: |release|
 
 .. _official GitHub repository: https://github.com/AngryMaciek/angry-moran-simulator
+.. _preliminary results: https://beta.briefideas.org/ideas/d292ad28e6818d20aad2286e1c9b6aa2

entrypoint.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+
+# create a non-root user "user" passed from the command line (or fallback);
+# set shell, home, conda group, init conda;
+# exec the rest (CMD) as "user"
+# ~AngryMaciek
+
+ID=${HOSTUID:-9001}
+useradd --shell /bin/bash -u $ID -o -c "" -m user
+export HOME=/home/user
+adduser user conda &> /dev/null
+/usr/sbin/gosu user /bin/bash -c "/mambaforge/bin/conda init bash &> /dev/null"
+exec /usr/sbin/gosu user "$@"

environment.yml

@@ -21,22 +21,20 @@
     - jiayi_anaconda
 
   dependencies:
-    - black=22.10.0
-    - coverage=7.0.0
-    - flake8=6.0.0
-    - jupyterlab=3.5.2
-    - make=4.3
-    - matplotlib=3.6.2
-    - numpy=1.24.0
-    - pandas=1.5.2
-    - pip=22.3.1
-    - pip:
-      - sphinx-rtd-theme==1.1.1
-    - pytest=7.2.0
-    - python=3.9.15
-    - recommonmark=0.7.1
-    - scipy=1.9.3
-    - seaborn=0.12.1
-    - sphinx=5.3.0
+    - black>=22.6.0
+    - coverage>=6.0
+    - flake8>=5.0.4
+    - jupyterlab>=3.3.4
+    - make>=4.3
+    - matplotlib>=3.3.4
+    - numpy>=1.19.5
+    - pandas>=1.1.5
+    - pytest>=6.2.5
+    - python>=3.6.15
+    - recommonmark>=0.7.1
+    - scipy>=1.5.3
+    - seaborn>=0.11.2
+    - sphinx>=5.1.1
+    - sphinx_rtd_theme>=1.2.2
 
 ...

moranpycess/MoranProcess.py

@@ -424,7 +424,6 @@ def simulate(self, generations):
             log_df.at[0, "Entropy"] = self.Entropy
 
         for g in range(generations):
-
             # select one individual to multiply
             selectedBirth = self._roulette_wheel_selection_Birth()
             # create a copy
@@ -446,9 +445,7 @@ def simulate(self, generations):
                     new_label = np.random.choice(
                         a=self.init_label_list,
                         size=1,
-                        p=self.TransitionMatrix[
-                            row_index,
-                        ],
+                        p=self.TransitionMatrix[row_index,],
                     )[0]
                     old_label = ind.label
                     ind.label = new_label

moranpycess/MoranProcess2D.py

@@ -484,7 +484,6 @@ def simulate(self, generations):
             log_df.at[0, "Entropy"] = self.Entropy
 
         for g in range(generations):
-
             # select one individual to multiply
             (x, y) = self._roulette_wheel_selection_Birth()
             selectedBirth = self.population[x, y]
@@ -508,9 +507,7 @@ def simulate(self, generations):
                         new_label = np.random.choice(
                             a=self.init_label_list,
                             size=1,
-                            p=self.TransitionMatrix[
-                                row_index,
-                            ],
+                            p=self.TransitionMatrix[row_index,],
                         )[0]
                         old_label = ind.label
                         ind.label = new_label