mdeck 2.3.0

package/examples/python/slides.md

@@ -0,0 +1,493 @@
+---
+theme: sketch
+meta:
+  title: "Introduction to Python"
+  author: "Tilman Schieber"
+  organization: "FHNW"
+  date: "2026-05-19"
+palette: graphite
+---
+
+---
+:::meta
+layout: title
+id: python-for-life-sciences
+:::
+# Python for Life Sciences.
+## A step-by-step introduction for Master's students.
+
+:::notes
+Welcome to the Python module. This session assumes no prior programming experience.
+
+- We'll move step by step — don't hesitate to interrupt with questions
+- All code runs live in the browser — no installation needed today
+- Goal: by the end you'll be able to load, inspect, and plot a dataset
+:::
+
+---
+:::meta
+layout: focus
+eyebrow: Why Python?
+id: the-tools-your-field-uses-are-written-in
+:::
+# The tools your field uses are *written in Python*.
+
+:::notes
+Python is the dominant language in both academia and industry for data-heavy work.
+Life sciences is no exception — bioinformatics, imaging, and clinical data analysis all run on Python.
+
+The ecosystem (NumPy, Pandas, Matplotlib, scikit-learn, BioPython) is unmatched.
+Point out that R is still common in statistics, but Python has largely converged as the lingua franca.
+:::
+
+---
+:::meta
+layout: chapter
+number: 1
+part: Getting Started
+description: Variables, types, and your first lines of code.
+id: variables-and-data-types
+:::
+# Variables and data types.
+
+:::notes
+Start here even if students have seen some Python before. We build from the ground up.
+Estimated time for this chapter: 20 minutes.
+:::
+
+---
+:::meta
+layout: split
+section: Variables
+id: variables-store-data
+props:
+  ratio: [3, 2]
+:::
+# A variable is a name for a value.
+:::slot left
+```python live editable copy
+name = "E. coli"
+genome_size = 4_641_652   # base pairs
+gc_content = 0.506        # fraction
+
+print(name, genome_size, gc_content)
+print(f"GC content: {gc_content:.1%}")
+```
+:::
+:::slot right
+No declarations: Python sees the type from the value.
+
+**Try it:** change `gc_content` to `0.65` and run again.
+:::
+
+:::notes
+A variable is just a name attached to a value. Python figures out the type automatically.
+
+Point out: no semicolons, no type declarations, no boilerplate. The `f"…"` string formats a value inside text; `:.1%` shows a fraction as a percentage.
+Encourage students to change the values and re-run — that's the point of the live block.
+:::
+
+---
+:::meta
+section: Data Types
+id: four-types-cover-most-biology-data
+:::
+# Four types cover most biology data.
+
+:::steps
+- **`int`** — whole numbers: counts, positions, indices
+- **`float`** — decimals: concentrations, p-values, fold changes
+- **`str`** — text: gene names, sequences, sample IDs
+- **`bool`** — True or False: significance flags, quality filters
+:::
+
+:::notes
+Reveal one type at a time and ask for an example from the lab before showing the next.
+
+Emphasise that booleans typically come from comparisons, not literal True/False. The next slide asks the room.
+:::
+
+---
+:::meta
+section: Data Types
+title: "Poll: the type of a p-value"
+id: poll-the-type-of-a-p-value
+:::
+# What type is a p-value?
+
+<poll room="p-value" options="int|float|str|bool" answer="float" />
+
+:::notes
+A quick check before moving on. Phones join with the QR code; start the deck with `mdeck run slides.md --network` so they can reach this computer.
+
+Answer: `float`; the tick button under the bars marks it. If many chose `bool`, they are thinking of the *significance flag* computed from it (`p < 0.05`): a good moment to show that comparisons produce booleans.
+:::
+
+---
+:::meta
+layout: split
+section: Strings
+props:
+  ratio: [3, 2]
+:::
+# Strings behave like sequences.
+:::slot left
+```python live editable copy
+dna = "ATGCGTAAGCTTGAC"
+
+print("Length:     ", len(dna))
+print("First codon:", dna[:3])
+print("A count:    ", dna.count("A"))
+print("Reversed:   ", dna[::-1])
+print("As RNA:     ", dna.replace("T", "U"))
+```
+:::
+:::slot right
+Slicing, counting and replacing work the same on any text.
+
+**Try it:** print the last codon with `dna[-3:]`.
+:::
+
+:::notes
+Strings are sequences — you can slice them just like a nucleotide sequence.
+`replace("T", "U")` is transcription in one line. The concepts transfer directly to BioPython later.
+:::
+
+---
+:::meta
+layout: chapter
+number: 2
+part: Collections
+description: Storing and accessing multiple values at once.
+:::
+# Lists and dictionaries.
+
+:::notes
+Most real data is not a single value. Lists and dictionaries are the two workhorse collections.
+Estimated time for this chapter: 25 minutes.
+:::
+
+---
+:::meta
+layout: split
+section: Lists
+props:
+  ratio: [3, 2]
+:::
+# A list holds values in order.
+:::slot left
+```python live editable copy
+conc = [0.12, 0.45, 0.33, 0.78, 0.21]
+
+print("Samples:", len(conc))
+print("First:  ", conc[0])
+print("Last:   ", conc[-1])
+print("Sorted: ", sorted(conc))
+print("Mean:   ", sum(conc) / len(conc))
+```
+:::
+:::slot right
+Counting starts at zero: `conc[0]` is the first item, `conc[-1]` the last.
+
+**Try it:** add a sixth value and watch the mean change.
+:::
+
+:::notes
+Lists maintain order and allow duplicates. Index from 0. Negative indices count from the end.
+Great for: time series, replicate measurements, ordered processing steps.
+
+Common mistake: students try index 1 for the first element. Drill 0-indexing early.
+:::
+
+---
+:::meta
+layout: split
+section: Dictionaries
+props:
+  ratio: [3, 2]
+:::
+# A dictionary looks values up by name.
+:::slot left
+```python live editable copy
+sample = {
+    "id": "S042",
+    "organism": "Mus musculus",
+    "tissue": "liver",
+    "weight_mg": 312,
+}
+
+print(sample["organism"])
+sample["weight_mg"] = 318   # update a field
+print(sample)
+```
+:::
+:::slot right
+One dictionary describes one sample: no column numbers to remember.
+
+**Try it:** add `"treated": True`.
+:::
+
+:::notes
+Dictionaries map keys to values. Perfect for structured records — one dictionary = one sample.
+Later, a list of dictionaries becomes a Pandas DataFrame. Plant that seed now.
+:::
+
+---
+:::meta
+layout: chapter
+number: 3
+part: Control Flow
+description: Making decisions and repeating operations across your data.
+:::
+# Decisions and loops.
+
+:::notes
+These two constructs — if and for — cover the vast majority of logic in data processing scripts.
+Estimated time for this chapter: 25 minutes.
+:::
+
+---
+:::meta
+layout: split
+section: Conditions
+props:
+  ratio: [3, 2]
+:::
+# `if` chooses a path.
+:::slot left
+```python live editable copy
+p_value = 0.023
+fold_change = 2.4
+
+if p_value < 0.05 and fold_change > 2:
+    print("Significant upregulation")
+elif p_value < 0.05:
+    print("Significant, modest effect")
+else:
+    print("Not significant")
+```
+:::
+:::slot right
+The indentation is the block: Python uses whitespace, not braces.
+
+**Try it:** set `fold_change = 1.5`.
+:::
+
+:::notes
+if / elif / else covers all branching. Indentation is not stylistic in Python — it is syntax.
+This trips up students from other languages or R. The colon and the indent are mandatory.
+Show what happens if you forget the colon: Python gives a SyntaxError.
+:::
+
+---
+:::meta
+layout: split
+section: Loops
+props:
+  ratio: [3, 2]
+:::
+# `for` repeats an action for every item.
+:::slot left
+```python live editable copy
+values = [1.2, 0.8, 2.1, 1.5, 0.9, 2.8]
+
+above = []
+for value in values:
+    if value > 1.0:
+        above.append(value)
+
+print(len(above), "of", len(values))
+print(above)
+```
+:::
+:::slot right
+Loop, test, collect: the core pattern of filtering data.
+
+**Try it:** count the values below 1.0 instead.
+:::
+
+:::notes
+for loops iterate over any collection. This pattern — loop, test, collect — is at the heart of
+almost every data processing script students will write.
+
+Press **D** and trace one value through the loop on the slide: into `value`, through the `if`, into `above`. Escape stops drawing; the drawing stays with the slide.
+:::
+
+---
+:::meta
+layout: chapter
+number: 4
+part: Functions
+description: Packaging logic so you can reuse and test it.
+:::
+# Functions package logic for reuse.
+
+:::notes
+Functions are the first step toward reusable, testable code.
+Motivate with: "you'll run this same calculation on 200 samples — write it once, call it 200 times."
+Estimated time for this chapter: 20 minutes.
+:::
+
+---
+:::meta
+layout: split
+section: Functions
+props:
+  ratio: [3, 2]
+:::
+# A function turns inputs into an output.
+:::slot left
+```python live editable copy
+def gc_content(seq):
+    """Return the GC fraction of a sequence."""
+    gc = seq.count("G") + seq.count("C")
+    return gc / len(seq)
+
+for seq in ["ATGCGC", "AATTAA", "GCGCGC"]:
+    print(seq, f"{gc_content(seq):.0%}")
+```
+:::
+:::slot right
+Write it once, then call it on every sample.
+
+**Try it:** add your own sequence to the list.
+:::
+
+:::notes
+def, parameters, return — that's the whole syntax.
+Walk through: define once, call many times with different inputs.
+The docstring (triple-quoted string after def) is best practice — introduce it early.
+:::
+
+---
+:::meta
+layout: chapter
+number: 5
+part: Scientific Python
+description: NumPy, Pandas, and Matplotlib — the three pillars.
+:::
+# The scientific stack.
+
+:::notes
+These three libraries are what make Python the dominant language in data science.
+Students won't write much pure Python in practice — they'll use these.
+Estimated time for this chapter: 30 minutes.
+:::
+
+---
+:::meta
+section: Scientific Python
+:::
+# Three libraries cover most life sciences workflows.
+
+:::steps
+- **NumPy** — fast arrays: calculate on a whole dataset at once
+- **Pandas** — tables: load, filter, group and summarise spreadsheet data
+- **Matplotlib** — plots, with control over every element
+:::
+
+:::notes
+Brief overview before diving in. The key message: these libraries handle the heavy lifting
+so students write less code and get faster, more reliable results than with pure Python loops.
+:::
+
+---
+:::meta
+layout: split
+section: NumPy
+props:
+  ratio: [3, 2]
+:::
+# NumPy calculates on whole arrays.
+:::slot left
+```python live copy
+import numpy as np
+
+m = np.array([1.2, 0.8, 2.1, 1.5, 0.9, 2.8])
+
+print("Mean:  ", m.mean().round(3))
+print("Std:   ", m.std().round(3))
+print("Median:", np.median(m))
+print("> 1.5: ", m[m > 1.5])
+```
+:::
+:::slot right
+`m[m > 1.5]` filters without a loop.
+
+Compare it with the `for` loop two chapters ago.
+:::
+
+:::notes
+NumPy operations apply to the whole array at once — no loops. This is both faster and more readable.
+The vectorised style takes getting used to but is worth learning early.
+Demo: ask students to predict what `m > 1.5` returns before running it.
+:::
+
+---
+:::meta
+layout: focus
+eyebrow: Key insight
+:::
+# Write operations on *arrays*, not on single values.
+
+:::notes
+This is the most important mental model shift from pure Python to scientific Python.
+Repeat it, let it sink in. Students who internalise this early write much cleaner code later.
+:::
+
+---
+:::meta
+layout: chapter
+number: 6
+part: Next Steps
+description: Where to go from here.
+id: keep-going
+:::
+# Keep going.
+
+:::notes
+Close with a roadmap. Students often feel lost after an intro — give them concrete next steps
+and point them to the best free resources.
+:::
+
+---
+:::meta
+section: Next Steps
+:::
+# What to learn next.
+
+- **Pandas** — load a CSV, filter rows, compute group statistics
+- **Matplotlib and Seaborn** — scatter plots, heatmaps, volcano plots
+- **scikit-learn** — classification, clustering, dimensionality reduction
+- **BioPython** — sequences, BLAST, GenBank and PDB files
+
+:::notes
+For self-study: the official Python tutorial for syntax, Pandas documentation for data work.
+Kaggle's free Python and Pandas courses are excellent and self-paced.
+For life sciences specifically: BioPython docs, and the Python for Bioinformatics textbook (Bassi).
+:::
+
+---
+:::meta
+layout: focus
+eyebrow: Remember
+:::
+# The best way to learn to code is to *write code*.
+
+:::notes
+Close on this. Programming is a skill — it takes practice. The first few weeks feel slow,
+then things click. Encourage daily practice, even small scripts. Point to the exercises.
+:::
+
+---
+:::meta
+layout: title
+:::
+# Questions?
+## Thank you — now open your laptops.
+
+:::notes
+Leave time for questions.
+Remind students where to find the course materials and how to reach you.
+The next session will cover Pandas and loading real datasets.
+:::

package/examples/showcase/.mdeck-backups/slides.drawings-2026-10-06T08-08-30Z.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "width": 1920,
+  "height": 1080,
+  "slides": {
+    "draw-on-any-slide": [
+      {"id":"pkpb2b:muw89tng0","tool":"pen","color":"#e11d48","size":6,"points":[[1247,286,0.5]]}
+    ]
+  }
+}

package/examples/showcase/.mdeck-backups/slides.drawings-2026-10-06T11-41-35Z.json

@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "width": 1920,
+  "height": 1080,
+  "slides": {
+    "draw-on-any-slide": [
+      {"id":"pkpb2b:muw89tng0","tool":"pen","color":"#e11d48","size":6,"points":[[1247,286,0.5]]}
+    ],
+    "give-the-talk": [
+      {"id":"pkpb2b:muwectdg0","tool":"pen","color":"#e11d48","size":6,"points":[[950,358,0.5],[917,358,0.5],[899,362,0.5],[877,369,0.5],[861,381,0.5],[851,391,0.5],[845,403,0.5],[838,421,0.5],[833,439,0.5],[831,453,0.5],[831,490,0.5],[833,506,0.5],[839,517,0.5],[849,525,0.5],[868,532,0.5],[895,536,0.5],[958,537,0.5],[998,533,0.5],[1043,522,0.5],[1087,505,0.5],[1132,483,0.5],[1181,452,0.5],[1207,433,0.5],[1235,409,0.5],[1257,386,0.5],[1275,364,0.5],[1287,341,0.5],[1294,318,0.5],[1297,295,0.5],[1297,270,0.5],[1290,245,0.5],[1270,214,0.5],[1241,186,0.5],[1205,169,0.5],[1142,159,0.5],[1061,157,0.5],[975,179,0.5],[878,227,0.5],[793,283,0.5],[709,354,0.5],[637,423,0.5],[587,486,0.5],[544,556,0.5],[519,618,0.5],[508,672,0.5],[510,716,0.5],[527,752,0.5],[558,779,0.5],[601,798,0.5],[653,809,0.5],[712,812,0.5],[775,810,0.5],[843,797,0.5],[961,744,0.5],[1006,711,0.5],[1055,668,0.5],[1095,620,0.5],[1126,571,0.5],[1141,534,0.5],[1147,501,0.5],[1149,467,0.5],[1146,443,0.5],[1130,424,0.5],[1094,413,0.5],[1047,420,0.5],[995,450,0.5],[953,487,0.5],[917,531,0.5],[886,571,0.5],[872,599,0.5],[856,633,0.5],[846,662,0.5],[843,691,0.5],[844,722,0.5],[856,739,0.5],[893,745,0.5],[949,740,0.5],[1015,717,0.5],[1093,675,0.5],[1174,620,0.5],[1232,574,0.5],[1261,543,0.5],[1292,508,0.5],[1313,480,0.5],[1341,420,0.5],[1339,409,0.5],[1318,400,0.5],[1254,406,0.5],[1155,442,0.5],[1035,512,0.5],[932,585,0.5],[836,667,0.5],[758,743,0.5],[724,785,0.5],[704,814,0.5],[686,843,0.5],[666,887,0.5],[659,916,0.5],[685,915,0.5],[767,878,0.5],[884,801,0.5],[977,728,0.5],[1051,667,0.5],[1140,590,0.5],[1218,521,0.5],[1260,481,0.5],[1325,417,0.5],[1334,405,0.5],[1334,399,0.5],[1306,412,0.5],[1172,492,0.5],[1112,530,0.5],[1079,553,0.5],[1039,582,0.5],[1016,601,0.5]]}
+    ]
+  }
+}

package/examples/showcase/img/mdeck.svg

@@ -0,0 +1,66 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="800" viewBox="0 0 960 800">
+  <!-- A Markdown file becoming a stack of slides. The colours come from the
+       deck's palette (var(--accent) …), so the picture follows the theme;
+       the fallbacks apply where it is shown as a plain image. -->
+  <style>
+    .mdk-paper { fill: var(--surface, #eef1fb); stroke: var(--rule, #d5dbf0); stroke-width: 3; }
+    .mdk-fold { fill: var(--rule, #d5dbf0); }
+    .mdk-shadow { fill: var(--ink, #0c1033); opacity: .12; }
+    .mdk-code { font-family: ui-monospace, 'JetBrains Mono', Menlo, Consolas, monospace; font-size: 30px; fill: var(--ink-soft, #2a2f55); }
+    .mdk-mark { fill: var(--accent, #1f3fd1); font-weight: 700; }
+    .mdk-quiet { fill: var(--muted, #5b6080); }
+    .mdk-slide { fill: var(--bg, #ffffff); stroke: var(--ink, #0c1033); stroke-width: 3; }
+    .mdk-accent { fill: var(--accent, #1f3fd1); }
+    .mdk-accent-2 { fill: var(--accent-2, #e8590c); }
+    .mdk-rule { fill: var(--rule, #d5dbf0); }
+    .mdk-on-accent { fill: var(--on-accent, #ffffff); font-family: var(--font-display, sans-serif); font-weight: 800; font-size: 96px; }
+    .mdk-title { fill: var(--ink, #0c1033); font-family: var(--font-display, sans-serif); font-weight: 800; font-size: 46px; }
+    .mdk-arrow { fill: none; stroke: var(--accent-2, #e8590c); stroke-width: 5; stroke-linecap: round; stroke-linejoin: round; }
+  </style>
+
+  <!-- The text file -->
+  <g transform="rotate(-5 230 400)">
+    <rect class="mdk-shadow" x="56" y="146" width="370" height="510" rx="18"/>
+    <path class="mdk-paper" d="M58 130 h290 l62 62 v438 a18 18 0 0 1 -18 18 h-316 a18 18 0 0 1 -18 -18 v-482 a18 18 0 0 1 18 -18 z"/>
+    <path class="mdk-fold" d="M348 130 v44 a18 18 0 0 0 18 18 h44 z"/>
+    <text class="mdk-code" x="84" y="232"><tspan class="mdk-mark">#</tspan> A talk</text>
+    <text class="mdk-code" x="84" y="300"><tspan class="mdk-mark">-</tspan> one idea</text>
+    <text class="mdk-code" x="84" y="344"><tspan class="mdk-mark">-</tspan> an example</text>
+    <text class="mdk-code mdk-mark" x="84" y="412">---</text>
+    <text class="mdk-code mdk-quiet" x="84" y="480">:::notes</text>
+    <text class="mdk-code mdk-quiet" x="84" y="524">pause here</text>
+    <text class="mdk-code mdk-quiet" x="84" y="568">:::</text>
+  </g>
+
+  <!-- From text to slides -->
+  <path class="mdk-arrow" d="M300 112 C 380 20, 560 22, 640 150" stroke-dasharray="2 16"/>
+  <path class="mdk-arrow" d="M612 138 l30 16 l4 -34"/>
+  <path class="mdk-accent" d="M470 60 l7 17 l17 7 l-17 7 l-7 17 l-7 -17 l-17 -7 l17 -7 z"/>
+  <path class="mdk-accent-2" d="M760 210 l5 12 l12 5 l-12 5 l-5 12 l-5 -12 l-12 -5 l12 -5 z"/>
+
+  <!-- The slides: a chapter, a statement, and a content slide in front -->
+  <g transform="rotate(9 680 330)">
+    <rect class="mdk-accent-2" x="440" y="200" width="480" height="270" rx="14"/>
+  </g>
+  <g transform="rotate(3 660 420)">
+    <rect class="mdk-accent" x="420" y="290" width="480" height="270" rx="14"/>
+    <text class="mdk-on-accent" x="452" y="386">2</text>
+    <rect class="mdk-accent-2" x="512" y="350" width="80" height="10" rx="5"/>
+  </g>
+  <g transform="rotate(-3 640 540)">
+    <rect class="mdk-shadow" x="412" y="420" width="480" height="270" rx="14"/>
+    <rect class="mdk-slide" x="400" y="404" width="480" height="270" rx="14"/>
+    <text class="mdk-title" x="432" y="470">A talk</text>
+    <rect class="mdk-accent" x="432" y="486" width="88" height="8" rx="4"/>
+    <rect class="mdk-accent" x="432" y="524" width="14" height="14" rx="3"/>
+    <rect class="mdk-rule" x="458" y="525" width="150" height="12" rx="6"/>
+    <rect class="mdk-accent" x="432" y="562" width="14" height="14" rx="3"/>
+    <rect class="mdk-rule" x="458" y="563" width="120" height="12" rx="6"/>
+    <rect class="mdk-accent" x="432" y="600" width="14" height="14" rx="3"/>
+    <rect class="mdk-rule" x="458" y="601" width="136" height="12" rx="6"/>
+    <rect class="mdk-accent-2" x="682" y="580" width="34" height="62" rx="4"/>
+    <rect class="mdk-accent" x="726" y="530" width="34" height="112" rx="4"/>
+    <rect class="mdk-accent-2" x="770" y="556" width="34" height="86" rx="4"/>
+    <rect class="mdk-accent" x="814" y="500" width="34" height="142" rx="4"/>
+  </g>
+</svg>

package/examples/showcase/slides.drawings.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "width": 1920,
+  "height": 1080,
+  "slides": {
+    "draw-on-any-slide": [
+      {"id":"tour:underline","tool":"pen","color":"#e11d48","size":7,"points":[[120,462,0.45],[135,464,0.48],[150,466,0.52],[165,467,0.55],[180,468,0.58],[195,469,0.61],[210,469,0.64],[225,468,0.66],[240,467,0.68],[255,465,0.7],[270,464,0.72],[285,462,0.73],[300,460,0.74],[315,459,0.75],[330,458,0.75],[345,458,0.75],[360,459,0.74],[375,460,0.73],[390,461,0.72],[405,463,0.71],[420,465,0.69],[435,467,0.67],[450,469,0.64],[465,470,0.62],[480,471,0.59],[495,472,0.56],[510,472,0.53],[525,471,0.49],[540,470,0.46],[555,468,0.43],[570,467,0.39],[585,465,0.36],[600,464,0.33],[615,462,0.3],[630,462,0.27],[645,461,0.25],[660,462,0.22],[675,462,0.2],[690,464,0.19],[705,466,0.17],[720,468,0.16]]},
+      {"id":"tour:circle","tool":"pen","color":"#e11d48","size":6,"points":[[226,491,0.5],[230,491,0.54],[235,491,0.57],[239,492,0.6],[243,494,0.64],[247,497,0.66],[250,500,0.69],[252,504,0.71],[254,508,0.73],[255,512,0.74],[256,516,0.75],[255,520,0.75],[254,524,0.75],[252,528,0.74],[250,532,0.73],[247,534,0.71],[244,537,0.69],[240,539,0.66],[237,541,0.63],[233,542,0.6],[229,543,0.57],[225,543,0.54],[221,543,0.5],[217,543,0.46],[213,541,0.43],[209,540,0.4],[206,538,0.36],[203,535,0.34],[200,531,0.31],[198,528,0.29],[196,523,0.27],[196,519,0.26],[196,515,0.25],[197,510,0.25],[199,506,0.25],[201,503,0.26],[204,500,0.27],[207,497,0.29],[211,495,0.31],[215,494,0.34],[219,493,0.37],[223,493,0.4],[227,493,0.43],[231,493,0.47],[235,495,0.5],[239,496,0.54]]}
+    ]
+  }
+}