creapy 0.1.0__py3-none-any.whl

creapy/__init__.py

@@ -0,0 +1,67 @@
+from creapy.formats import read_table, detect_format, guess_mapping, FIXATION_FIELDS, SACCADE_FIELDS
+from creapy.formats import load_prolab_export, load_prolab_data_export, load_prolab_event_export
+from creapy.formats import load_prolab_data_export_chunked, load_prolab_aoi_metrics_export, aoi_metrics_summary
+from creapy.gaze.base import StimulusGaze
+from creapy.gaze.fixation import FixationData
+from creapy.gaze.saccade import SaccadeData
+from creapy.gaze.convert import fixations_to_saccades, saccades_to_fixations
+from creapy.aoi.aoi import AOI
+from creapy.aoi.sequence import aoi_sequence, transition_matrix, show_scarf_plot, show_transition_matrix, first_fixation_order
+from creapy.stats import coefficient_k, fixation_k, participant_table, group_comparison, show_group_boxplot
+from creapy.stats import value_series, show_measure_curve, split_by_group
+from creapy.stats import participant_rqa, cross_recurrence_table, show_recurrence_plot
+from creapy.stats import participant_periodogram, dominant_period, show_periodogram, morlet_scalogram, show_scalogram
+from creapy.similarity.heatmatch_result import PairwiseSimilarityResult, HeatMatchSimilarityResult
+from creapy.misc.utils import natural_sorted, find_images
+import os
+
+__version__ = "0.1.0"
+
+
+def load_fixations(path, mapping=None, **mapping_kwargs):
+    """Fixation table (CSV/TSV/Excel with one row per fixation, or a Tobii Pro Lab Data export) -> (df, mapping)."""
+    df = read_table(path)
+    if detect_format(df.columns) in ('tobii_data_export', 'tobii_event_export'):
+        df, guessed = load_prolab_export(df)
+    else:
+        guessed = guess_mapping(df, FIXATION_FIELDS)
+    guessed.update(mapping or {})
+    guessed.update(mapping_kwargs)
+    return df, guessed
+
+
+def load_saccades(path, mapping=None, **mapping_kwargs):
+    """Saccade table (one row per saccade) -> (df, mapping) with the sac_* keys of SACCADE_FIELDS."""
+    df = read_table(path)
+    guessed = guess_mapping(df, SACCADE_FIELDS)
+    guessed.update(mapping or {})
+    guessed.update(mapping_kwargs)
+    return df, guessed
+
+
+def datasets_by_stimulus(df, mapping, stimulus_paths=None, is_fixation=True):
+    """Split a table into per-stimulus (FixationData, SaccadeData) pairs: {stimulus -> (fix, sac)}."""
+    if isinstance(stimulus_paths, (str, os.PathLike)):
+        found = find_images(str(stimulus_paths))
+        stimulus_paths = {}
+        for stim in df[mapping['stim_col']].unique():
+            key = str(stim).lower()
+            stimulus_paths[stim] = found.get(key, found.get(os.path.splitext(key)[0], str(stim)))
+    datasets = {}
+    for stim, df_stim in df.groupby(mapping['stim_col']):
+        path = stimulus_paths[stim] if stimulus_paths is not None else str(stim)
+        datasets[stim] = build_pair(df_stim, path, mapping, is_fixation)
+    return datasets
+
+
+def build_pair(df_stim, path, mapping, is_fixation=True):
+    """(FixationData, SaccadeData) of one stimulus from its rows and image path."""
+    if is_fixation:
+        fix = FixationData(df_stim, path, **mapping)
+        df_sac, sac_mapping = fixations_to_saccades(fix.df, fix.mapping)
+        sac = SaccadeData(df_sac, path, img=fix.img, scale=1., time_unit=fix.time_unit, **sac_mapping)
+    else:
+        sac = SaccadeData(df_stim, path, **mapping)
+        df_fix, fix_mapping = saccades_to_fixations(sac.df, sac.mapping)
+        fix = FixationData(df_fix, path, img=sac.img, scale=1., time_unit=sac.time_unit, **fix_mapping)
+    return fix, sac

creapy/aoi/aoi.py

@@ -0,0 +1,142 @@
+import numpy as np
+import functools
+import matplotlib.patches as patches
+import matplotlib.patheffects as pe
+import matplotlib.path as mpath
+from shapely import area, centroid, covers
+from shapely.ops import unary_union
+from shapely.geometry import Point, Polygon, LinearRing, box
+
+
+class AOI:
+    """One area of interest: a named shapely geometry in image pixels (x right, y down)."""
+
+    def __init__(self, name="Unnamed", geom=None, paths=None):
+        assert (geom is None) != (paths is None), "EITHER 'geom' OR 'paths' must be provided, but not both"
+        self.__name = name
+        self.__geom = geom if paths is None else AOI.__multiple_paths_to_single_geom(paths)
+        self.__path = AOI.__single_geom_to_single_path(self.__geom)
+        self.__disconnected_polygons = AOI.__extract_disconnected_polygons(self.__geom)
+
+    @property
+    def name(self):
+        """The AOI's name (read-only)."""
+        return self.__name
+
+    @property
+    def geom(self):
+        """The shapely geometry (Polygon or MultiPolygon) in image pixels, read-only."""
+        return self.__geom
+
+    def area(self):
+        """Area of the AOI in square pixels."""
+        return float(area(self.__geom))
+
+    def contains(self, points):
+        """True for each point inside or on the boundary of the AOI."""
+        return covers(self.__geom, points)
+
+    @staticmethod
+    def rectangle(name, x0, y0, x1, y1):
+        """Rectangular AOI from two opposite corners (x0, y0), (x1, y1) in pixels."""
+        return AOI(name=name, geom=box(min(x0, x1), min(y0, y1), max(x0, x1), max(y0, y1)))
+
+    @staticmethod
+    def polygon(name, vertices):
+        """Polygon AOI from a list of (x, y) vertices in pixels, at least three."""
+        assert len(vertices) >= 3, "A polygon AOI needs at least three corners."
+        return AOI(name=name, geom=Polygon(vertices).buffer(0))
+
+    def to_record(self):
+        """Dict {'name', 'wkt'} describing the AOI as text (WKT), for saving AOI sets to JSON; see from_record."""
+        return {'name': self.__name, 'wkt': self.__geom.wkt}
+
+    @staticmethod
+    def from_record(record):
+        """Rebuild an AOI from a to_record() dict."""
+        from shapely import wkt
+        return AOI(name=record['name'], geom=wkt.loads(record['wkt']))
+
+    def show(self, ax, color='yellow', alpha=0.4, label=True):
+        """Draw the AOI on a matplotlib axes as a translucent patch."""
+        ax.add_patch(patches.PathPatch(self.__path, facecolor=color, alpha=alpha, edgecolor=color, linewidth=1.5))
+        if not label:
+            return
+        polygons = sorted([(area(polygon), polygon) for polygon in self.__disconnected_polygons], reverse=True)
+        center = centroid(polygons[0][1])
+        ax.text(center.x, center.y, self.__name, ha='center', va='center', color="black",
+                path_effects=[
+                    pe.Stroke(linewidth=4, foreground='white', alpha=0.7),
+                    pe.Normal()
+                ])
+        for _, polygon in polygons[1:]:
+            center_ = centroid(polygon)
+            ax.plot([center.x, center_.x], [center.y, center_.y], color='black', alpha=0.3, linestyle='--')
+
+    @staticmethod
+    def __multiple_paths_to_single_geom(paths):
+        polygons = [AOI.__single_path_to_multiple_geoms(path) for path in paths]
+        flattened_polygons = functools.reduce(lambda a, b: a + b, polygons)
+        return unary_union(flattened_polygons)
+
+    @staticmethod
+    def __extract_disconnected_polygons(geom):
+        if geom.geom_type == 'Polygon':
+            return [geom]
+        elif geom.geom_type == 'MultiPolygon':
+            return list(geom.geoms)
+        elif geom.geom_type == 'GeometryCollection':
+            return [g for g in geom.geoms if isinstance(g, Polygon)]
+        else:
+            return []
+
+    @staticmethod
+    def __single_path_to_multiple_geoms(path):
+        polys = []
+        vertices = path.vertices
+        codes = path.codes
+        if codes is None:
+            if np.allclose(vertices[0], vertices[-1]):
+                polys.append(Polygon(vertices))
+            else:
+                polys.append(LinearRing(vertices))
+            return polys
+
+        current = []
+        for vert, code in zip(vertices, codes):
+            if code == mpath.Path.MOVETO:
+                if current:
+                    ring = np.array(current)
+                    if np.allclose(ring[0], ring[-1]):
+                        polys.append(Polygon(ring))
+                    else:
+                        polys.append(LinearRing(ring))
+                current = [vert]
+            else:
+                current.append(vert)
+
+        if current:
+            ring = np.array(current)
+            if np.allclose(ring[0], ring[-1]):
+                polys.append(Polygon(ring))
+            else:
+                polys.append(LinearRing(ring))
+        return polys
+
+    @staticmethod
+    def __single_geom_to_single_path(geom):
+        if geom.geom_type == 'Polygon':
+            verts = np.array(geom.exterior.coords)
+            codes = ([mpath.Path.MOVETO] + [mpath.Path.LINETO] * (len(verts) - 2) + [mpath.Path.CLOSEPOLY])
+            return mpath.Path(verts, codes)
+        elif geom.geom_type == 'MultiPolygon':
+            all_verts = []
+            all_codes = []
+            for polygon in geom.geoms:
+                verts = np.array(polygon.exterior.coords)
+                codes = ([mpath.Path.MOVETO] + [mpath.Path.LINETO] * (len(verts) - 2) + [mpath.Path.CLOSEPOLY])
+                all_verts.extend(verts)
+                all_codes.extend(codes)
+            return mpath.Path(np.array(all_verts), all_codes)
+        else:
+            raise ValueError(f"Unsupported geometry type: {geom.geom_type}")

creapy/aoi/sequence.py

@@ -0,0 +1,174 @@
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+from matplotlib.patches import Patch
+from matplotlib.collections import PolyCollection
+
+
+OUTSIDE = 'outside'
+
+
+def aoi_sequence(fix, names=None, include_outside=True):
+    """Which AOI each fixation fell into, in viewing order."""
+    if names is None:
+        names = list(fix.areas_of_interest)
+    label = np.full(len(fix.df), OUTSIDE, dtype=object)
+    assigned = np.zeros(len(fix.df), dtype=bool)
+    for name in names:
+        inside = np.asarray(fix.areas_of_interest[name].contains(fix.fix_points)) & ~assigned
+        label[inside] = name
+        assigned |= inside
+    df_seq = pd.DataFrame({'participant': fix.subj_index.to_numpy(),
+                           'trial': fix.df[fix.trial_col].to_numpy() if fix.trial_col else 1,
+                           't': fix.t.to_numpy(), 'dur': fix.fix_dur.to_numpy(), 'aoi': label})
+    df_seq['order'] = df_seq.groupby(['participant', 'trial']).cumcount() + 1
+    if not include_outside:
+        df_seq = df_seq[df_seq['aoi'] != OUTSIDE]
+    return df_seq.reset_index(drop=True)
+
+
+def collapse_runs(df_seq):
+    """Merge consecutive fixations in the same AOI into one visit."""
+    ls = []
+    for (subj, trial), df_ in df_seq.groupby(['participant', 'trial'], sort=False):
+        aoi = df_['aoi'].to_numpy()
+        new_run = np.r_[True, aoi[1:] != aoi[:-1]]
+        run_id = np.cumsum(new_run)
+        for _, df_run in df_.groupby(run_id, sort=False):
+            ls.append({'participant': subj, 'trial': trial, 'aoi': df_run['aoi'].iloc[0],
+                       't_start': float(df_run['t'].iloc[0]), 't_end': float(df_run['t'].iloc[-1]),
+                       'n_fixations': int(len(df_run)), 'dwell': float(df_run['dur'].sum())})
+    return pd.DataFrame.from_records(ls)
+
+
+def transition_matrix(fix, names=None, include_outside=False, normalize='row', per_participant_weight=True):
+    """AOI -> AOI transitions between consecutive visits, self-transitions excluded."""
+    df_seq = aoi_sequence(fix, names=names, include_outside=include_outside)
+    labels = (names if names is not None else list(fix.areas_of_interest)) + ([OUTSIDE] if include_outside else [])
+    counts = pd.DataFrame(0., index=labels, columns=labels)
+    if len(df_seq) == 0:
+        return counts
+    df_runs = collapse_runs(df_seq)
+    ls = []
+    for (subj, trial), df_ in df_runs.groupby(['participant', 'trial'], sort=False):
+        aoi = df_['aoi'].to_numpy()
+        if len(aoi) < 2:
+            continue
+        df_t = pd.DataFrame({'from': aoi[:-1], 'to': aoi[1:]})
+        df_t['participant'] = subj
+        ls.append(df_t)
+    if not ls:
+        return counts
+    df_trans = pd.concat(ls)
+    if per_participant_weight:
+        df_trans['w'] = 1. / df_trans.groupby('participant')['from'].transform('size')
+    else:
+        df_trans['w'] = 1.
+    pivot = df_trans.pivot_table(index='from', columns='to', values='w', aggfunc='sum', fill_value=0.)
+    counts = counts.add(pivot, fill_value=0.).loc[labels, labels]
+    if per_participant_weight:
+        counts = counts * df_trans['participant'].nunique()
+    if normalize == 'row':
+        row_sums = counts.sum(axis=1)
+        counts = counts.div(row_sums.where(row_sums > 0, np.nan), axis=0)
+    elif normalize == 'all':
+        total = counts.to_numpy().sum()
+        counts = counts / total if total > 0 else counts
+    else:
+        assert normalize is None, f"Unknown normalize: {normalize}"
+    return counts
+
+
+def show_transition_matrix(ax, matrix, cmap='Blues', fmt='{:.0%}', text_color_switch=0.6):
+    """Draw a transition_matrix() as a heat-table on ax (rows = from, columns = to)."""
+    values = matrix.to_numpy(dtype=float)
+    im = ax.imshow(np.nan_to_num(values), cmap=cmap, vmin=0, vmax=np.nanmax(values) if np.isfinite(values).any() else 1)
+    ax.set_xticks(range(len(matrix.columns)))
+    ax.set_yticks(range(len(matrix.index)))
+    ax.set_xticklabels(matrix.columns, rotation=45, ha='right')
+    ax.set_yticklabels(matrix.index)
+    ax.set_xlabel("to")
+    ax.set_ylabel("from")
+    vmax = np.nanmax(values) if np.isfinite(values).any() else 1
+    for i in range(values.shape[0]):
+        for j in range(values.shape[1]):
+            v = values[i, j]
+            if np.isnan(v):
+                continue
+            ax.text(j, i, fmt.format(v) if fmt else f"{v:.2f}", ha='center', va='center', fontsize=8,
+                    color='white' if v > text_color_switch * vmax else 'black')
+    return im
+
+
+def aoi_palette(names, include_outside=True):
+    """Dict AOI name -> RGBA colour (tab10 cycle), plus a grey for 'outside' unless include_outside=False."""
+    palette = plt.get_cmap('tab10')
+    colors = {name: palette(i % 10) for i, name in enumerate(names)}
+    if include_outside:
+        colors[OUTSIDE] = (0.35, 0.35, 0.38, 1.)
+    return colors
+
+
+def show_scarf_plot(ax, fix, names=None, subjects=None, colors=None, relative_time=True, outside_alpha=0.35,
+                    row_height=0.8):
+    """Scarf plot: one row per participant, viewing time on x."""
+    df_seq = aoi_sequence(fix, names=names, include_outside=True)
+    if names is None:
+        names = list(fix.areas_of_interest)
+    if colors is None:
+        colors = aoi_palette(names)
+    if subjects is None:
+        subjects = list(fix.subjects)
+    dur_s = df_seq['dur'] / (1000. if fix.dur_unit == 'ms' else 1.)
+    df_seq = df_seq.assign(dur_s=dur_s.to_numpy())
+    row_of = {subj: row for row, subj in enumerate(subjects)}
+    df_plot = df_seq[df_seq['participant'].isin(row_of)]
+    if relative_time:
+        t_start = df_plot['t'] - df_plot.groupby('participant')['t'].transform('min')
+    else:
+        t_start = df_plot['t']
+    rows = df_plot['participant'].map(row_of).to_numpy(dtype=float)
+    x0 = t_start.to_numpy(dtype=float)
+    x1 = x0 + df_plot['dur_s'].to_numpy(dtype=float)
+    y0 = rows - row_height / 2
+    y1 = rows + row_height / 2
+    verts = np.stack([np.column_stack([x0, y0]), np.column_stack([x1, y0]),
+                      np.column_stack([x1, y1]), np.column_stack([x0, y1])], axis=1)
+    rgba = np.array([colors.get(a, (0.5, 0.5, 0.5, 1.)) for a in df_plot['aoi']], dtype=float)
+    rgba[df_plot['aoi'].to_numpy() == OUTSIDE, 3] = outside_alpha
+    ax.add_collection(PolyCollection(verts, facecolors=rgba, edgecolors='none'))
+    ax.set_xlim(0, float(x1.max()) if len(x1) else 1.)
+    if len(subjects) <= 40:
+        ax.set_yticks(range(len(subjects)))
+        ax.set_yticklabels([str(s) for s in subjects], fontsize=7 if len(subjects) > 30 else 9)
+    else:
+        step = 10 if len(subjects) <= 200 else 25
+        ax.set_yticks(range(0, len(subjects), step))
+        ax.set_yticklabels([str(subjects[i]) for i in range(0, len(subjects), step)], fontsize=7)
+        ax.set_ylabel(f"participants ({len(subjects)})")
+    ax.set_ylim(len(subjects) - 0.4, -0.6)
+    ax.set_xlabel("Viewing time (s)")
+    handles = [Patch(color=colors[name], label=name) for name in names] + \
+              [Patch(color=colors[OUTSIDE], alpha=outside_alpha, label=OUTSIDE)]
+    ax.legend(handles=handles, loc='upper left', bbox_to_anchor=(1.01, 1.), fontsize=8, frameon=False)
+    return df_seq
+
+
+def first_fixation_order(fix, names=None):
+    """In which order each participant first visited the AOIs."""
+    df_seq = aoi_sequence(fix, names=names, include_outside=False)
+    if names is None:
+        names = list(fix.areas_of_interest)
+    ls = []
+    for subj in fix.subjects:
+        df_ = df_seq[df_seq['participant'] == subj]
+        firsts = df_.groupby('aoi')['t'].min().sort_values()
+        rank = {name: i + 1 for i, name in enumerate(firsts.index)}
+        row = {'participant': subj}
+        row.update({name: rank.get(name, np.nan) for name in names})
+        ls.append(row)
+    return pd.DataFrame.from_records(ls)
+
+
+if __name__ == '__main__':
+    pass

creapy/examples/README.md

@@ -0,0 +1,7 @@
+# creapy example dataset (synthetic)
+
+Generated by `creapy.examples.make_example`: twelve invented viewers (six 'expert', six 'layperson'), two generated pictures (1600 x 1200 px), 30 s of simulated viewing each.
+
+`demo_fixations.csv`: one row per fixation with participant, group, age, trial, image, t_start (ms), dur (ms), x, y (px), pupil (arbitrary).
+
+No real eye-tracking data is involved.

creapy/examples/__init__.py

@@ -0,0 +1,127 @@
+import os
+import numpy as np
+import pandas as pd
+from PIL import Image, ImageDraw
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+WIDTH, HEIGHT = 1600, 1200
+SEED = 2026
+SHIPPED = ("demo_fixations.csv", "demo_picture_A.png", "demo_picture_B.png")
+
+
+def example_folder():
+    """Folder holding the example files."""
+    if all(os.path.exists(os.path.join(HERE, name)) for name in SHIPPED):
+        return HERE
+    folder = os.path.join(os.path.expanduser("~"), ".creapy", "example")
+    os.makedirs(folder, exist_ok=True)
+    return folder
+
+
+def example_dataset():
+    """Path of the example fixation CSV (demo_fixations.csv); pictures and table are generated on first call."""
+    folder = example_folder()
+    csv_path = os.path.join(folder, "demo_fixations.csv")
+    if not os.path.exists(csv_path):
+        make_example(folder)
+    return csv_path
+
+
+def draw_picture_a(path):
+    """Paint synthetic picture A."""
+    img = Image.new('RGB', (WIDTH, HEIGHT), (214, 203, 182))
+    d = ImageDraw.Draw(img)
+    d.rectangle([0, 760, WIDTH, HEIGHT], fill=(96, 112, 84))
+    d.rectangle([0, 0, WIDTH, 760], fill=(176, 196, 214))
+    d.ellipse([520, 260, 860, 700], fill=(150, 72, 60))
+    d.ellipse([610, 140, 770, 300], fill=(222, 186, 150))
+    d.ellipse([1180, 160, 1300, 280], fill=(250, 232, 120))
+    d.polygon([(1000, 760), (1250, 460), (1500, 760)], fill=(92, 84, 110))
+    d.rectangle([120, 820, 420, 1120], fill=(70, 60, 50))
+    img.save(path)
+
+
+def draw_picture_b(path):
+    """Paint synthetic picture B."""
+    img = Image.new('RGB', (WIDTH, HEIGHT), (58, 52, 60))
+    d = ImageDraw.Draw(img)
+    d.polygon([(0, HEIGHT), (WIDTH, 0), (WIDTH, 220), (0, HEIGHT - 220)], fill=(110, 96, 88))
+    d.ellipse([260, 380, 520, 720], fill=(190, 150, 110))
+    d.ellipse([320, 250, 460, 390], fill=(230, 200, 170))
+    d.ellipse([1080, 400, 1340, 740], fill=(110, 130, 180))
+    d.ellipse([1140, 270, 1280, 410], fill=(230, 200, 170))
+    rng = np.random.default_rng(SEED)
+    for _ in range(40):
+        x, y = rng.uniform(600, 1000), rng.uniform(820, 1150)
+        d.ellipse([x, y, x + 24, y + 24], fill=(240, 220, 90))
+    d.rectangle([700, 60, 900, 200], fill=(200, 70, 60))
+    img.save(path)
+
+
+def simulate_viewer(rng, attractors, weights, n_fix, focal, t_total=30.):
+    """Simulate one viewer on one picture: a list of dicts with t_start (ms), dur (ms), x, y (px) and pupil."""
+    ls = []
+    t = 0.05
+    xy = np.array([WIDTH / 2, HEIGHT / 2], dtype=float)
+    k = 0
+    while t < t_total and k < n_fix:
+        if k < 3:
+            target = np.array([WIDTH / 2, HEIGHT / 2]) + rng.normal(0, 90, 2)
+        else:
+            idx = rng.choice(len(attractors), p=weights)
+            ax, ay, spread = attractors[idx]
+            target = np.array([ax, ay]) + rng.normal(0, spread, 2)
+        xy = target if rng.random() > 0.3 else xy + rng.normal(0, 40, 2)
+        xy = np.clip(xy, [10, 10], [WIDTH - 10, HEIGHT - 10])
+        dur = float(np.exp(rng.normal(np.log(260 if focal else 190), 0.35)))
+        dur = dur * (0.8 if k < 3 else 1.0)
+        ls.append({'t_start': round(t * 1000, 1), 'dur': round(dur, 1), 'x': round(xy[0], 1), 'y': round(xy[1], 1),
+                   'pupil': round(float(rng.normal(900 if focal else 850, 40)), 1)})
+        t += (dur + rng.uniform(25, 60)) / 1000.
+        k += 1
+    return ls
+
+
+def make_example(folder):
+    """Write the whole example (two pictures, fixation table, README) into `folder`."""
+    img_a = os.path.join(folder, "demo_picture_A.png")
+    img_b = os.path.join(folder, "demo_picture_B.png")
+    draw_picture_a(img_a)
+    draw_picture_b(img_b)
+    rng = np.random.default_rng(SEED)
+    pictures = {
+        'demo_picture_A.png': [(690, 220, 60), (690, 480, 110), (1240, 220, 40), (270, 970, 90), (1250, 620, 120)],
+        'demo_picture_B.png': [(390, 320, 55), (1210, 340, 55), (390, 550, 90), (1210, 570, 90), (800, 980, 130),
+                               (800, 130, 50)],
+    }
+    weights = {
+        ('demo_picture_A.png', 'expert'): [0.32, 0.25, 0.08, 0.15, 0.20],
+        ('demo_picture_A.png', 'layperson'): [0.25, 0.20, 0.30, 0.10, 0.15],
+        ('demo_picture_B.png', 'expert'): [0.24, 0.24, 0.12, 0.12, 0.08, 0.20],
+        ('demo_picture_B.png', 'layperson'): [0.18, 0.18, 0.12, 0.12, 0.30, 0.10],
+    }
+    ls = []
+    for i in range(12):
+        group = 'expert' if i < 6 else 'layperson'
+        participant = f"P{i + 1:02d}"
+        for trial, (picture, attractors) in enumerate(pictures.items(), start=1):
+            focal = group == 'expert'
+            n_fix = int(rng.integers(70, 110))
+            for row in simulate_viewer(rng, attractors, weights[(picture, group)], n_fix, focal):
+                row.update({'participant': participant, 'group': group, 'trial': trial, 'image': picture,
+                            'age': int(25 + i * 2)})
+                ls.append(row)
+    df = pd.DataFrame.from_records(ls)[['participant', 'group', 'age', 'trial', 'image', 't_start', 'dur', 'x', 'y',
+                                        'pupil']]
+    df.to_csv(os.path.join(folder, "demo_fixations.csv"), index=False)
+    with open(os.path.join(folder, "README.md"), 'w', encoding='utf-8') as f:
+        f.write("# creapy example dataset (synthetic)\n\n"
+                "Generated by `creapy.examples.make_example`: twelve invented viewers (six 'expert', six "
+                "'layperson'), two generated pictures (1600 x 1200 px), 30 s of simulated viewing each.\n\n"
+                "`demo_fixations.csv`: one row per fixation with participant, group, age, trial, image, t_start (ms), "
+                "dur (ms), x, y (px), pupil (arbitrary).\n\nNo real eye-tracking data is involved.\n")
+    return df
+
+
+if __name__ == '__main__':
+    print(example_dataset())