feat(plotting): concatenate plots in a subfigure layout (#21)

* feat(combine): create class that combines subfigures

* refactor(py3.8): make it compatible with python3.8+

Since the project assumes python >=3.8, and 3.8 is also the lowest
supported version now that 3.12 is out, this class shouldn't use python
>=3.11 features.

https://devguide.python.org/versions/

* tests(combine): write tests and use pathlib for all paths

* test(github): run tests in github action

* fix(combine): allow simultaneous calls to combine class from parallel python runtimes

* docs(README): add usage section

* chore(concat): add download link and shorten docstring header

* feat(combine): support any file type also supported by Imagemagick

* chore(combine): warn about vector formats and test against jpg

* docs(combine): add imagemagick note on vector images

* chore(combine): resolve merge conflict

.github/workflows/tests.yml

@@ -0,0 +1,46 @@
+name: Tests
+
+on:
+  - push
+  - pull_request
+
+jobs:
+  build:
+    # timeout-minutes: 460
+    name: ${{ matrix.python-version }} / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+        os:
+          - ubuntu-latest
+          # - macos-latest
+          # - windows-latest  # Haven't figured out how ImageMagick should be installed on win32 yet
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      # You can test your matrix by printing the current Python version
+      - name: Display Python version
+        run: python -c "import sys; print(sys.version)"
+
+      - name: Upgrade pip
+        run: |
+          pip install --upgrade pip
+          pip --version
+
+      - name: Install Poetry
+        run: |
+          pipx install poetry
+          poetry --version
+
+      - name: Install dependencies
+        run: |
+          poetry install
+
+      - name: Test with pytest
+        run: |
+          poetry run pytest

README.md

@@ -138,3 +138,68 @@ plt.show()
 | `hex_colors.png` | hex_colors_example.png |
 | :--------: | :--------: | 
 | ![colors](./assets/hex_colors.png) | ![colors](./assets/hex_colors_example.png) |
+
+## `combine`
+
+Sometimes, plots might be related and better placed as subfigures in a larger figure. If
+combining the plots using the `subfigure` environment in latex or similar is not an
+option, this is easily done with [`imagemagick`](https://imagemagick.org/index.php) in a
+systematic way.
+
+The `Combine` class within the `concat` module implements such procedures, and is also
+conveniently available from the `combine` function in `cosmoplots`.
+
+An example is shown below. Also see the [`tests`](./tests/) directory for more examples.
+A `help` method that prints the `imagemagick` commands that are used under the hood is
+also available.
+
+```python
+import matplotlib as mpl
+import matplotlib.pyplot as plt
+import numpy as np
+
+import cosmoplots
+
+mpl.style.use("cosmoplots.default")
+
+
+def plot(i) -> None:
+    """Create a simple plot."""
+    a = np.exp(np.linspace(-3, 5, 100))
+    fig = plt.figure()
+    ax = fig.add_subplot()
+    ax.set_xlabel("X Axis")
+    ax.set_ylabel("Y Axis")
+    ax.semilogy(a)
+    plt.savefig(f"./assets/{i}.png")
+    plt.close(fig)
+
+plot(1)
+plot(2)
+plot(3)
+plot(4)
+plot(5)
+plot(6)
+plot(7)
+plot(8)
+plot(9)
+plot(10)
+# See `convert -list font` for all available fonts.
+figs = [f"./assets/{i}.png" for i in range(1, 11)]
+cosmoplots.combine(*figs).using(
+    font="JetBrainsMonoNL-NFM-Medium",
+    fontsize=60,
+    gravity="southeast",
+    pos=(100, 200),
+    color="green",
+).in_grid(w=3, h=4).with_labels(  # Specifying labels is optional
+    "one", "four", "three", "two", "eight", "six", "seven", "five", "nine", "ten"
+).save("./assets/concat.png")
+
+# Note that cosmoplots.combine() == cosmoplots.Combine().combine()
+cosmoplots.combine().help()
+# Or equivalently
+cosmoplots.Combine().help()
+```
+
+![concat](./assets/concat.png)

cosmoplots/__init__.py

@@ -3,5 +3,6 @@
 from .axes import *
 from .colors import *
 from .figure_defs import *
+from .concat import *
 
 __version__ = version(__package__)