angrymaciek/angry-moran-simulator

A general game-theoretical framework to carry out scientific simulations of populations' evolution according to the Moran model 🧮

Moran [Py]cess

General information

The following Python package presents a general game-theoretical framework to carry out scientific simulations according to the Moran model. Registering distinct types of individuals together with specification of payoffs between them allows to replicate evolution of the population and observe growth dynamics.

For more information please visit the project's homepage.

angry-moran-simulator's Issues

[JOSS Review] Insufficient documentation for plotting functions.

This is a part of the JOSS review (openjournals/joss-reviews#2643)

Documentation in 'documentation.md' is not sufficient for the MoranProcess plotting methods. (PlotSize, PlotAvgBirthPayoff, PlotAvgDeathPayoff, PlotBirthFitness, PlotDeathFitness, PlotEntropy).Please amend by providing explicit examples.

Proper documentation

Move the docs into GH Pages or ReadTheDocs, change md to rst; use sphinx; add CI and README shield, add proper code comments.

Binder notebook

Set binder for an interactive usecase notebook.

Calculate theoretical transition probabilities

Describe the solution you'd like
Include additional columns in the simulation df which would hold the calculated probabilities.

Additional context
At each given time point in the simulation one may calculate the theoretical probability for the population to move from a state (A,B,C,D...) to (A-1,B+1,C,D...) [and all the others]. The class MoranProcess could hold an attribute TransitionMatrix of size (#types, #types) which would contain the probability values to move from a given state to all others. The rows would denote: TYPE-1 and the columns: TYPE+1.

Python error on use case test

# initiate Moran Process

size_list = [10, 990]
label_list = ["swerve", "straight"]

BirthPayoffMatrix = np.array([[1, 0.1], [10, -1000]])
DeathPayoffMatrix = np.array([[1, 1], [1, 1]])

mp = ms.MoranProcess(
    size_list=size_list,
    label_list=label_list,
    BirthPayoffMatrix=BirthPayoffMatrix,
    DeathPayoffMatrix=DeathPayoffMatrix,
)

# simulate evolution
random.seed(0)
simulation2 = mp.simulate(generations=10000)

refactor: include new cool repo mechanisms

Include some new cool GitHub repo mechanisms I have learned recently:

• .gitattributes w/ langauges, .gitignore refactor
• new issue/PR templates
• codeowners
• gitpod configuration
• contributor covenant shield?
• CITATION.cff?
• Dockerfile run/dev switch
• PR template
• JOBI info

---

• dev env: YAML or requirements.TXT? conda is needed anyway...
• pyproject/setup, version?
• Makefile: as in capsule (pytodstyle, mypy?)
• refactor ci's? PR workflows: size labels, title check, auto assign
• pre-commit hooks

---

• Contributing: better instructions, specific rules, more tests
• version bump
• gitpod test
• publish workflow?
• clean old published versions

conda upload

Set automatic upload to anaconda cloud in the CI upon merge to master.

Codecov does not display full pkg coverage measurement

Describe the bug
codecov decided to show only coverage for __init__.py now; presumably since the unit testing import changes <?>

To Reproduce
GOTO codecov page for project

Expected behavior
Display measurement for all package files

Automatic push to Dockerhub

Following: https://github.com/zavolanlab/multiqc-plugins

After pushing a tagged version a docker image should be build automatically and pushed to dockerhub.

pip upload

Set automatic upload to pip in the CI upon merge to master.

Python modularisation

double-check the modularisation setup in the init.

Missing features for version 1.0.0

There are some essential features of this repository which need to be addressed before reaching a first major release:

• write-up the general description in the README file
• raise code coverage to 100%
• include aesthetic modifications to the simulation scheme
• add Moran Process on 2D grid
• add Moran Process on 3D grid
• scan-through README and fill in the gaps.
• write-up the package documentation

Add Entropy to the results df

Calculate the entropy of the distirbution of distinct individuals in the population (at each generation).
Add this values to the simulation df.

[JOSS Review] Writing quality suggestions for software paper

This is a part of the JOSS review (openjournals/joss-reviews#2643)

Some very minor suggestions to improve clarity of the software paper:

• ESS versus EES is not consistent. Please fix to the correct abbreviation (=ESS?)
• Intro L1: "Population is created by" would be more clearly written as "A population consists of individuals" or similar
• Intro L2-4: "Population characteristics, including: ..." would be more clearly written as something like "Population characteristics (e.g., reproduction, .... etc) change over time as a result of evolutionary mechanisms"
• Intro L4: "A complicated network of..."
• Intro L12: EES or ESS?
• Intro L13: should it be "evolutionarily" stable?
• Statement of need L1: Perhaps mention the name of the package in the first sentence?
• Statement of need L2: "Contrary to cellular automata"? Perhaps revise for clarity
• Statement of need L13: "An open source license"
• Example (A) L2: Define "player"

[JOSS Review] Conda installation "Conflicts found"

This is a part of the JOSS review (openjournals/joss-reviews#2643)

Environment creation as suggested in the documentation yields a bunch of conflicts found by conda. I was able to amend this by relaxing the version constraints in the .yml file like so:

---

name: moranpycess

channels:
- bioconda
- conda-forge

dependencies:
- matplotlib=3.3
- numpy=1.19
- pandas
- pip=20.1
- python=3.7

...

Also, as suggested by @xin-huang, I would request that you add any additional dependencies needed for plotting, such as seaborn.

Codecov

Change coveralls to codecov in the CI.

[JOSS REVIEW] Suggestions for Documentation

This is a part of the JOSS review (openjournals/joss-reviews#2643)

1. I found a Jupyter notebook https://github.com/AngryMaciek/angry-moran-simulator/blob/master/tests/usecase.ipynb could reproduce the examples. I suggest the authors provide a link to this notebook in their documentation explicitly, so that users can quickly replicate the examples.
2. After installing the package successfully in my computer with Ubuntu 18.04, I failed to replicate the examples in https://github.com/AngryMaciek/angry-moran-simulator/blob/master/tests/usecase.ipynb at first. I have to manually install jupyter, pyyaml and seaborn under the virtual environment moranpycess before successfully running the notebook. Thus, I suggest the authors add jupyter, pyyaml and seaborn into https://github.com/AngryMaciek/angry-moran-simulator/blob/master/env/main.yml, so that users can easily reproduce the examples.
3. As the checklist suggests, a statement of need is required in the documentation. Besides, the authors may provide a link to https://github.com/AngryMaciek/angry-moran-simulator/blob/master/env/main.yml, so that users can find dependencies for this package easily.
4. Typos in https://github.com/AngryMaciek/angry-moran-simulator/blob/master/documentation.md
   • The word "sygnature" should be "signature"

Custom exceptions

• add exceptions file with custom exceptsions as in the mlem project

[JOSS REVIEW] Suggestions for Software Paper

This is a part of the JOSS review (openjournals/joss-reviews#2643)

1. As the checklist suggests, a Summary section is required in the paper.
2. Although the authors discussed some other simulators (DEAP and Axelrod) in the statement of need, I suggest the authors separate these discussion into a State of the field section, as the checklist suggests, or merge them into the Introduction section.