There is no opportunity to communicate with the other participant. Neither of you will learn the other’s choice until both decisions have been submitted. Please make your choice on the next page.

The two decisions jointly determine both your payoff and the other participant’s payoff as follows:

Welcome to the experiment

Your decision

Results

Make an offer

Survey

Other guesses: {% for other in others %} {{ other.guess }}{% if not loop.last %}, {% endif %} {% endfor %}

	The other participant cooperates	The other participant does not cooperate
{{ "You cooperate" if you else "You do not cooperate" }}	{{ C.PAYOFF_MATRIX[you, other] \| fmtnum(pre="$", places=2) }} for you {{ C.PAYOFF_MATRIX[other, you] \| fmtnum(pre="$", places=2) }} for the other participant

Round	Your number
{{ round }}	{{ data.number }}

Round	You	Partner
{{ round }}	{% if player.within(round=round).cooperate %} Cooperated {% else %} Defected {% endif %}	{% if other.within(round=round).cooperate %} Cooperated {% else %} Defected {% endif %}

``` !!! warning Only use `| safe` inside ` {% endblock main %} ``` [See the counter example](https://github.com/mrpg/uproot-examples/tree/main/counter) · [counter_alpine example](https://github.com/mrpg/uproot-examples/tree/main/counter_alpine) (with Alpine.js) ## Example: live form validation Validate input as the user types: ```python class Registration(Page): fields = dict( username=StringField(label="Username"), ) @live def check_username(page, player, username: str): # Check if username is available taken = username.lower() in ["admin", "root", "system"] return {"available": not taken} ``` ```javascript document.getElementById("username").addEventListener("input", (e) => { uproot.invoke("check_username", e.target.value).then(result => { if (result.available) { showValid("Username available"); } else { showError("Username taken"); } }); }); ``` ## Example: fetching data Load data dynamically without page reload: ```python class Dashboard(Page): @live def get_stats(page, player): return { "total_responses": player.session.response_count, "average_score": player.session.average_score, } ``` ```javascript uproot.onReady(() => { // Fetch stats when page loads uproot.invoke("get_stats").then(stats => { document.getElementById("responses").innerText = stats.total_responses; document.getElementById("average").innerText = stats.average_score; }); }); // Refresh stats periodically setInterval(() => { uproot.invoke("get_stats").then(updateDashboard); }, 5000); ``` ## Async operations Live methods can be async for I/O operations. Keep reads and writes of `player`, `player.session`, and other uproot storage outside the part of the method that awaits whenever you can: ```python @live async def process_data(page, player, data: dict): # Do slow external work first. result = await some_async_function(data) # Then update uproot state without another await in between. player.processed = result return {"status": "complete"} ``` ### Advanced concurrency note Special care must be taken when you want to allow live methods to interleave with `async`. Specifically: Live method calls from the same browser page are not a transaction queue. If an advanced `@live` method reaches an `await`, another live method call for the same participant may run before the first one resumes. This matters only for methods whose correctness depends on a check-then-act sequence across an `await`. Avoid this pattern: ```python @live async def submit_once(page, player, payload: dict): if player.submitted: raise ValueError("Already submitted") result = await external_service(payload) player.result = result player.submitted = True ``` Prefer doing awaited work before entering the state-sensitive section, or keep the state-sensitive section free of awaits: ```python @live async def submit_once(page, player, payload: dict): result = await external_service(payload) if player.submitted: raise ValueError("Already submitted") player.result = result player.submitted = True ``` For most live methods, including the examples in this guide, this is not a concern because the method does not await while it is reading or updating uproot state. ## Example: real-effort task Live methods are ideal for real-effort tasks where participants interact repeatedly without page reloads: ```python class Sumhunt(Page): timeout = 120 @live def get_matrix(page, player): if player.matrix is None: player.matrix = generate_matrix(...) return player.matrix @live def propose_solution(page, player, solution: list[int]): if sum(solution) == TARGET and all(x in player.matrix for x in solution): player.solutions += 1 player.matrix = generate_matrix(...) # New puzzle return True return False ``` ```javascript // Fetch puzzle on page load uproot.onReady(() => { uproot.invoke("get_matrix").then(updateDisplay); }); // Submit answer and get next puzzle uproot.invoke("propose_solution", selectedNumbers).then(correct => { if (correct) { uproot.invoke("get_matrix").then(updateDisplay); } }); ``` [See the sumhunt example](https://github.com/mrpg/uproot-examples/tree/main/sumhunt) ## Summary | Feature | Purpose | |---------|---------| | `@live` decorator | Make method callable from JavaScript | | `uproot.invoke("method", args)` | Call live method from JavaScript | | Return value | Data returned to JavaScript Promise | | Type hints | Automatic parameter validation | | `uproot.onReady(fn)` | Run when WebSocket connects | | `uproot.onReconnect(fn)` | Run after reconnection | | `uproot.onDisconnect(fn)` | Run when connection lost | For broadcasting updates to multiple participants, see [Real-time interactions](https://uproot.science/multiplayer/real-time.md). --- Source: https://uproot.science/building/alpinejs.md # Using Alpine.js uproot includes [Alpine.js](https://alpinejs.dev/start-here), a lightweight JavaScript framework for adding interactivity to templates. It is already loaded—no setup required. ## Essentials ```html+jinja

Now you see me

Hello,

``` ## Global stores For state shared across the page, use `Alpine.store()`: ```html+jinja

Score:

``` ## Constants in JavaScript If your app’s `C` class sets `__export__`, those constants are available as `C` in scripts and Alpine expressions (`window.C`). See [Using constants](https://uproot.science/building/pages.md#using-constants). ## With live methods Combine Alpine stores with `uproot.invoke()` for reactive server communication: ```html+jinja

``` [counter_alpine example](https://github.com/mrpg/uproot-examples/tree/main/counter_alpine) · [sumhunt example](https://github.com/mrpg/uproot-examples/tree/main/sumhunt) · [encryption_task example](https://github.com/mrpg/uproot-examples/tree/main/encryption_task) ## Quick reference | Directive | Purpose | Example | |-----------|---------|---------| | `x-data` | Create reactive scope | `x-data="{ open: false }"` | | `x-text` | Set text content | `x-text="message"` | | `x-show` | Toggle visibility | `x-show="isVisible"` | | `x-model` | Two-way bind input | `x-model="answer"` | | `x-for` | Loop over array | `x-for="item in items"` | | `@click` | Click handler | `@click="count++"` | | `@keydown.enter` | Enter key handler | `@keydown.enter="submit()"` | | `:class` | Conditional classes | `:class="{ 'active': on }"` | | `:disabled` | Conditional disable | `:disabled="!ready"` | | `$store` | Access global store | `$store.task.value` | ## Learn more [Alpine.js documentation](https://alpinejs.dev/start-here) --- Source: https://uproot.science/multiplayer/groups.md # Grouping participants Many experiments require participants to interact in pairs or small groups. uproot makes grouping easy with the `GroupCreatingWait` page type, which automatically forms groups as participants arrive. ## Groups are lazy Groups are only created when participants reach a `GroupCreatingWait` page. uproot does not pre-assign groups when a session starts. Grouping happens at runtime as participants arrive. This means the number of groups depends on how many participants actually show up, not on how many were expected. ## Basic group formation Create a wait page that groups participants by subclassing `GroupCreatingWait` and setting `group_size`: ```python class WaitForPartner(GroupCreatingWait): group_size = 2 ``` When participants reach this page, they wait until enough others arrive to form a group. Once a group forms, all members advance to the next page together. A wait page only groups participants who have actually opened it. For example, if you advance participants to the wait page from the [admin interface](https://uproot.science/running/admin.md) while their browser is closed, they join a group once they come back and the page loads. Participants are also only grouped with others on the same page: if [`Between`](https://uproot.science/building/operators.md#between) gives participants different page orders, a wait page never groups them with someone who is on a different page at the same position. ```python page_order = [ WaitForPartner, GamePage, Results, ] ``` [See the prisoners_dilemma example](https://github.com/mrpg/uproot-examples/tree/main/prisoners_dilemma) ## Assigning roles with `after_grouping` Use the `after_grouping` callback to assign roles or initialize group members when the group forms: ```python class GroupPlease(GroupCreatingWait): group_size = 2 @classmethod def after_grouping(page, group): for player, is_dictator in zip(group.players, [True, False]): player.dictator = is_dictator ``` The callback receives the `group` object and runs exactly once when the group is created. All players in the group can then access their assigned attributes. A participant only joins a group after the wait page’s own [`early`](https://uproot.science/reference/page-methods.md#early) and [`before_always_once`](https://uproot.science/reference/page-methods.md#before_always_once) methods have finished for them. So anything these methods save on `player` is already there when `after_grouping` runs. [See the dictator_game example](https://github.com/mrpg/uproot-examples/tree/main/dictator_game) · [trust_game example](https://github.com/mrpg/uproot-examples/tree/main/trust_game) · [ultimatum_game example](https://github.com/mrpg/uproot-examples/tree/main/ultimatum_game) · [gift_exchange_game example](https://github.com/mrpg/uproot-examples/tree/main/gift_exchange_game) ### Using class attributes for role values You can define role values as class attributes for cleaner code: ```python class GroupPlease(GroupCreatingWait): group_size = 2 watch_values = (True, False) @classmethod def after_grouping(page, group): for player, watched in zip(group.players, page.watch_values): player.watched = watched ``` [See the observed_diary example](https://github.com/mrpg/uproot-examples/tree/main/observed_diary) ## Accessing group members ### `group.players` Get all players in a group as a `StorageBunch` using the virtual field: ```python for player in group.players: player.payoff = 10 ``` The `StorageBunch` supports iteration, filtering, and bulk operations. #### Basic iteration ```python # Sum contributions from all group members total = sum(p.contribution for p in group.players) # Unpack directly (e.g. in SynchronizingWait.all_here) p1, p2 = group.players ``` #### Filtering with `_` The `_` symbol is a field referent: a placeholder that stands for “each player” in a filter expression. When you write `_.cooperate == True`, uproot builds a comparison object that gets evaluated against each player in the collection. ```python # Players who cooperated cooperators = group.players.filter(_.cooperate == True) # Players with a score above 50 high_scorers = session.players.filter(_.score > 50) # Combine multiple conditions (all must be true) eligible = session.players.filter(_.present == True, _.age >= 18) ``` `_` supports all comparison operators: `==`, `!=`, `>`, `>=`, `<`, `<=`. You can also chain attribute access. For instance, `_.group.round` refers to each player’s group’s round field. !!! note `_` builds a lazy comparison, so `_.active` alone (without a comparison operator) tests for truthiness. To check for `False`, write `_.active == False` explicitly. #### Finding a single player `find_one()` returns exactly one player matching the criteria. It raises an error if zero or multiple players match. ```python dictator = group.players.find_one(dictator=True) leader = group.players.find_one(first_mover=True) ``` #### Extracting values with `each` `each()` collects a field from every player into a list: ```python # Get all contributions as a list contributions = group.players.each("contribution") # → [10, 20, 15] # Multiple fields return named tuples data = group.players.each("name", "score", simplify=False) # → [data(name='Alice', score=10), data(name='Bob', score=20)] ``` #### Bulk assignment with `assign` `assign()` sets a field on every player from an iterable: ```python group.players.assign("role", ["buyer", "seller"]) ``` #### Running a function on all players with `apply` `apply()` calls a function once per player: ```python group.players.apply(set_payoff) ``` See [Synchronizing progress](https://uproot.science/multiplayer/synchronization.md#using-apply-for-bulk-operations) for a full example. ### `player.other_in_group` For two-person groups, access the other player via the virtual field: ```python other = player.other_in_group if player.cooperate and other.cooperate: player.payoff = 10 ``` Raises an error if the group does not have exactly two members. [See the prisoners_dilemma example](https://github.com/mrpg/uproot-examples/tree/main/prisoners_dilemma) · [twobytwo example](https://github.com/mrpg/uproot-examples/tree/main/twobytwo) ### `player.others_in_group` For groups of any size, get all other members (excluding the current player): ```python for other in player.others_in_group: notify(player, other, "Hello!") ``` ## Group-level data storage Access the shared group storage with `player.group`: ```python class Calculate(SynchronizingWait): @classmethod def all_here(page, group): # Store a value at the group level group.total_contribution = sum(p.contribution for p in group.players) ``` In templates, access group data: ```html+jinja

Your group contributed {{ player.group.total_contribution }} in total.

``` `session.groups` lists every group in the session. In a multi-app config, pass `app=` to keep only groups created in that app: ```python for group in session.groups(app=__name__): print(group.name, len(group.players)) ``` ## Larger groups For experiments with more than two players per group, simply increase `group_size`: ```python class GroupPlease(GroupCreatingWait): group_size = 3 ``` Use the same patterns for accessing members: ```python class Sync(SynchronizingWait): @classmethod def all_here(page, group): total = sum(p.contribution for p in group.players) for player in group.players: player.payoff = ENDOWMENT - player.contribution + MPCR * total ``` [See the public_goods_game example](https://github.com/mrpg/uproot-examples/tree/main/public_goods_game) · [beauty_contest example](https://github.com/mrpg/uproot-examples/tree/main/beauty_contest) · [minimum_effort_game example](https://github.com/mrpg/uproot-examples/tree/main/minimum_effort_game) ## Manual group creation For custom matching logic, you can create groups programmatically using `create_group()` and `create_groups()` instead of `GroupCreatingWait`. This is useful when you need to: - Match participants based on survey responses - Form groups of different sizes - Sort or balance groups by some criteria ### Basic manual grouping Use `SynchronizingWait` to wait for all participants, then create groups in the `all_here` callback: ```python class WaitForEveryone(SynchronizingWait): synchronize = "session" @classmethod def all_here(page, session): # Get all players and sort alphabetically by name all_players = sorted(session.players, key=lambda p: p.name) if len(all_players) == 1: # Only one player create_group(session, all_players) else: # Split into two groups of roughly equal size mid = len(all_players) // 2 group_a = all_players[:mid] group_b = all_players[mid:] create_groups(session, [group_a, group_b]) class ShowGroup(Page): @classmethod def templatevars(page, player): group_members = sorted(player.group.players, key=lambda p: p.name) return dict( group_name=player.group.name, group_members=group_members, ) page_order = [ WaitForEveryone, ShowGroup, ] ``` [See the grouping example](https://github.com/mrpg/uproot-examples/tree/main/grouping) · [grouping_arbitrary_size example](https://github.com/mrpg/uproot-examples/tree/main/grouping_arbitrary_size) · [grouping_one_spare example](https://github.com/mrpg/uproot-examples/tree/main/grouping_one_spare) · [group_with_dropout example](https://github.com/mrpg/uproot-examples/tree/main/group_with_dropout) ### `create_group()` Creates a single group from a list of players: ```python # Create a group from specific players gid = create_group(session, [player1, player2]) # With a custom group name gid = create_group(session, members, gname="custom_name") # Allow reassigning players already in groups gid = create_group(session, members, overwrite=True) ``` ### `create_groups()` Creates multiple groups at once: ```python # Create pairs from a list of players all_players = list(session.players) pairs = [[all_players[i], all_players[i+1]] for i in range(0, len(all_players), 2)] gids = create_groups(session, pairs) ``` ### `add_to_group()` Adds players to an existing group. This is useful when latecomers need to join a group that has already been created: ```python # Add a single player add_to_group(session.groups[0], player) # Add multiple players add_to_group(session.groups[0], [player1, player2]) # Allow reassigning players already in a group add_to_group(session.groups[0], player, overwrite=True) ``` Players receive sequential `member_id` values starting after the existing members. ### Grouping by attribute Match participants based on their responses: ```python class WaitAndMatch(SynchronizingWait): synchronize = "session" @classmethod def all_here(page, session): # Separate players by their preference prefer_a = [p for p in session.players if p.preference == "A"] prefer_b = [p for p in session.players if p.preference == "B"] # Match players with different preferences for p1, p2 in zip(prefer_a, prefer_b): create_group(session, [p1, p2]) ``` ## Groups in multi-app configs When a config contains multiple apps that each use `GroupCreatingWait`, groups from a previous app are automatically cleared when participants reach a new `GroupCreatingWait` page. This means each app forms its own independent groups without manual cleanup. ## Complete example: prisoner’s dilemma Here is a complete two-player game showing group formation, decision collection, and payoff calculation: ```python DESCRIPTION = "Prisoner's dilemma" SUGGESTED_MULTIPLE = 2 class C: PAYOFF_MATRIX = { # (you cooperate, other cooperates): your payoff (True, True): 10, (True, False): 0, (False, True): 15, (False, False): 3, } class Instructions(Page): pass class GroupPlease(GroupCreatingWait): group_size = 2 class Dilemma(Page): fields = dict( cooperate=RadioField( label="Do you wish to cooperate?", choices=[(True, "Yes"), (False, "No")], ), ) class Sync(SynchronizingWait): @classmethod def all_here(page, group: GroupType) -> None: for player in group.players: player.payoff = C.PAYOFF_MATRIX[ player.cooperate, player.other_in_group.cooperate, ] class Results(Page): pass page_order = [ Instructions, GroupPlease, Dilemma, Sync, Results, ] ``` [See the full prisoners_dilemma example](https://github.com/mrpg/uproot-examples/tree/main/prisoners_dilemma) ## Summary | | Purpose | |--|---------| | `GroupCreatingWait` | Wait page that forms groups automatically | | `group_size` | Number of players per group | | `after_grouping(page, group)` | Callback when group forms | | `group.players` | All players in a group | | `player.other_in_group` | The other player (2-person groups) | | `player.others_in_group` | All other players in the group | | `session.players` | All players in a session | | `player.group` | Access group-level storage | | `create_group()` | Programmatically create a group | | `add_to_group()` | Add players to an existing group | --- Source: https://uproot.science/multiplayer/synchronization.md # Synchronizing progress In multiplayer experiments, you often need to wait for all group members to reach a certain point before continuing. The `SynchronizingWait` page type handles this automatically and provides a callback to process all players’ data together. ## Basic synchronization Create a wait page that synchronizes players by subclassing `SynchronizingWait`: ```python class WaitForAll(SynchronizingWait): pass ``` When a participant reaches this page, they wait until all other group members arrive. Once everyone is present, they all advance together. ```python page_order = [ GroupPlease, # Form groups first Decision, # Each player makes a decision WaitForAll, # Wait for all decisions Results, # Show results ] ``` ## Processing data with `all_here` The `all_here` callback runs exactly once when all group members have arrived. This is where you calculate outcomes based on everyone’s choices: ```python class Sync(SynchronizingWait): @classmethod def all_here(page, group): total = sum(p.contribution for p in group.players) for player in group.players: player.payoff = ENDOWMENT - player.contribution + MPCR * total ``` The callback receives the `group` object and has access to all players’ data. [See the public_goods_game example](https://github.com/mrpg/uproot-examples/tree/main/public_goods_game) · [beauty_contest example](https://github.com/mrpg/uproot-examples/tree/main/beauty_contest) · [minimum_effort_game example](https://github.com/mrpg/uproot-examples/tree/main/minimum_effort_game) ## Calculating payoffs A common pattern is to calculate payoffs for all players in `all_here`. Here is how the prisoner’s dilemma looks up each player’s payoff in a payoff matrix: ```python class C: PAYOFF_MATRIX = { # (you cooperate, other cooperates): your payoff (True, True): 10, (True, False): 0, (False, True): 15, (False, False): 3, } class Sync(SynchronizingWait): @classmethod def all_here(page, group: GroupType) -> None: for player in group.players: player.payoff = C.PAYOFF_MATRIX[ player.cooperate, player.other_in_group.cooperate, ] ``` Each key of `PAYOFF_MATRIX` is a pair of decisions: first that of the player who receives the payoff, then that of the other player. Saving the result as `player.payoff` puts it in your data export. [See the prisoners_dilemma example](https://github.com/mrpg/uproot-examples/tree/main/prisoners_dilemma) ### Using apply for bulk operations You can also use `apply()` to run a function on all players: ```python class Sync(SynchronizingWait): @classmethod def set_payoff(page, player): other = player.other_in_group if player.claim + other.claim <= 100: player.payoff = player.claim @classmethod def all_here(page, group): group.players.apply(page.set_payoff) ``` [See the focal_point example](https://github.com/mrpg/uproot-examples/tree/main/focal_point) · [prisoners_dilemma_fancy example](https://github.com/mrpg/uproot-examples/tree/main/prisoners_dilemma_fancy) ## Finding specific players Use `find_one()` to locate players with specific attributes: ```python class Sync(SynchronizingWait): @classmethod def all_here(page, group): dictator = group.players.find_one(dictator=True) recipient = group.players.find_one(dictator=False) dictator.payoff = cu(10) - dictator.give recipient.payoff = dictator.give ``` [See the dictator_game example](https://github.com/mrpg/uproot-examples/tree/main/dictator_game) · [trust_game example](https://github.com/mrpg/uproot-examples/tree/main/trust_game) · [ultimatum_game example](https://github.com/mrpg/uproot-examples/tree/main/ultimatum_game) ## Session-level synchronization By default, `SynchronizingWait` synchronizes within the group. To synchronize across the entire session instead: ```python class WaitForSession(SynchronizingWait): synchronize = "session" @classmethod def all_here(page, session): # Runs when ALL participants in the session have arrived session.total_participants = len(session.players) ``` Note that when `synchronize = "session"`, the callback receives the `session` object instead of `group`. ## Custom synchronization with `wait_for` Override the `wait_for` method for custom synchronization logic: ```python class CustomWait(SynchronizingWait): @classmethod def wait_for(page, player): # Return list of PlayerIdentifiers to wait for # Default implementation returns player.group.players return player.group.players ``` ## Synchronization in repeated games When using `Rounds`, each round typically needs its own synchronization point: ```python page_order = [ GroupPlease, Rounds( Decision, Sync, # Sync after each round RoundResults, n=3, ), FinalResults, ] ``` The `all_here` callback runs once per round, allowing you to calculate round-specific outcomes: ```python class Sync(SynchronizingWait): @classmethod def all_here(page, group): for player in group.players: set_payoff(player) # Payoff for this round ``` In templates, you can access the current round number: ```html+jinja

Round {{ player.round }} results

``` [See the prisoners_dilemma_repeated example](https://github.com/mrpg/uproot-examples/tree/main/prisoners_dilemma_repeated) ## Accessing historical data in repeated games Use `player.within()` to access data from specific rounds: ```python def digest(session): for group in session.groups: player1 = group.players.find_one(member_id=0) for round in range(1, player1.round + 1): # Get this player’s choice in a specific round choice = player1.within(round=round).get("cooperate") ``` [See the prisoners_dilemma_repeated example](https://github.com/mrpg/uproot-examples/tree/main/prisoners_dilemma_repeated) ## Complete example: public goods game Here is a complete example showing synchronization with a three-player group: ```python ENDOWMENT = cu("10") MPCR = cu("0.5") # Marginal Per Capita Return class GroupPlease(GroupCreatingWait): group_size = 3 class Contribute(Page): fields = dict( contribution=DecimalField( label="How much do you contribute to the group account?", min=0, max=ENDOWMENT, ), ) @classmethod def templatevars(page, player): group_size = GroupPlease.group_size multiplier = MPCR * group_size return dict( endowment=ENDOWMENT, group_size=group_size, multiplier=multiplier, ) class Sync(SynchronizingWait): @classmethod def all_here(page, group): total = sum(p.contribution for p in group.players) for player in group.players: player.payoff = ENDOWMENT - player.contribution + MPCR * total class Results(Page): @classmethod def templatevars(page, player): total = sum(p.contribution for p in player.group.players) return dict(total=total) page_order = [ GroupPlease, Contribute, Sync, Results, ] ``` [See the full public_goods_game example](https://github.com/mrpg/uproot-examples/tree/main/public_goods_game) ## Detecting presence In classroom or lab experiments you sometimes need to know which participants are actively present before forming groups or proceeding. The `detect_presence` pattern uses a short time window during which participants must signal that they are there: ```python from time import time as now class C: DETECTION_PERIOD = 30.0 # seconds class RaiseHands(Page): @classmethod def timeout(page, player): if player.session.get("detection_period_until") is None: player.session.detection_period_until = now() + C.DETECTION_PERIOD for p in player.session.players: p.present = False return player.session.detection_period_until - now() @classmethod def may_proceed(page, player): return now() >= player.session.detection_period_until @live def set_presence(page, player, new_value: bool): player.present = new_value return new_value ``` After the page completes, `player.present` tells you whether each participant signalled their presence. You can then use this in `show()`, `all_here()`, or when forming groups. [See the full detect_presence example](https://github.com/mrpg/uproot-examples/tree/main/detect_presence) ## Summary | Feature | Purpose | |---------|---------| | `SynchronizingWait` | Wait page that syncs group members | | `all_here(page, group)` | Callback when all members arrive | | `synchronize = "group"` | Sync within group (default) | | `synchronize = "session"` | Sync entire session | | `wait_for(page, player)` | Custom sync logic | | `group.players.find_one()` | Find player by attribute | | `group.players.apply()` | Run function on all players | | `player.within(round=n)` | Access data from specific round | --- Source: https://uproot.science/multiplayer/real-time.md # Real-time interactions uproot supports real-time communication between participants through WebSockets. This page covers broadcasting updates to multiple participants. For the basics of live methods (the `@live` decorator and `uproot.invoke`), see [Live methods](https://uproot.science/building/live-methods.md). ## Two patterns: return values vs. notifications There are two ways to send data back to the browser: 1. **Return values:** Data goes back to the caller only. 2. **Notifications:** Data is pushed to one or more participants. ```python @live async def post_offer(page, player, price: float): player.my_offer = price # Broadcast to everyone (notification) notify(player, player.session.players, price, event="NewOffer") # Return to the caller only return {"posted": price} ``` Use return values for request-response patterns. Use `notify` for broadcasting to multiple participants. ## Broadcasting with `notify` `notify` sends data to one or more participants. By default it only delivers to recipients currently on the sender’s page (`where=sender.show_page`): ```python # Notify one player notify(player, other_player, data) # Notify all players in a group notify(player, player.group.players, data) # Notify all players in a session notify(player, player.session.players, data) # Notify everyone except the sender notify(player, player.others_in_group, data) ``` The first argument is the sender (used to determine the current page context). The second is the recipient(s). Use `where=...` to deliver regardless of the recipient’s current page, or pass a page index to target a specific page. ### Custom events Name your notifications with the `event` parameter: ```python notify(player, player.session.players, market_data, event="MarketUpdate") ``` Listen for specific events in JavaScript: ```javascript uproot.onCustomEvent("MarketUpdate", (event) => { refreshMarketDisplay(event.detail.data); }); ``` ### Default event handling Without a custom event name, data goes to `uproot.receive`: ```python notify(player, other_player, "Hello!") ``` ```javascript uproot.receive = (data) => { console.log(data); // "Hello!" }; ``` ## `send_to` for server-initiated updates Use `send_to` when you do not have a sender context (like in background tasks): ```python from uproot.smithereens import send_to send_to(player, data) send_to(session.players, data, event="StatusUpdate") ``` ## Example: live text observation One participant types while another watches in real-time: ```python class Diary(Page): @live async def typed(page, player, text: str): observer = player.other_in_group notify(player, observer, text) ``` ```javascript // Writer textarea.oninput = () => { uproot.invoke("typed", textarea.value); }; // Observer uproot.receive = (text) => { display.innerText = text; }; ``` [See the observed_diary example](https://github.com/mrpg/uproot-examples/tree/main/observed_diary) ## Example: collaborative drawing Multiple participants drawing on a shared canvas: ```python class Draw(Page): @live async def stroke(page, player, points: list, color: str): with player.session as session: session.strokes.append({"points": points, "color": color}) # Send to others (not the sender) notify(player, player.others_in_session, {"points": points, "color": color}, event="NewStroke") ``` ```javascript uproot.onCustomEvent("NewStroke", (event) => { drawStroke(event.detail.data.points, event.detail.data.color); }); ``` [See the drawing_board example](https://github.com/mrpg/uproot-examples/tree/main/drawing_board) ## Example: real-time market A trading interface where participants post and accept offers: ```python class Market(Page): @live async def post_offer(page, player, price: float): player.my_offer = price # Broadcast updated market to everyone notify(player, player.session.players, list(player.session.offers), event="MarketUpdate") return {"posted": price} @live async def accept_offer(page, player, seller_id: str): seller = player.session.players.get(seller_id) price = seller.my_offer player.bought_at = price seller.sold_at = price seller.my_offer = None # Notify the seller directly notify(player, seller, price, event="OfferAccepted") # Update market for everyone notify(player, player.session.players, list(player.session.offers), event="MarketUpdate") return {"bought_at": price} ``` ```javascript uproot.onCustomEvent("MarketUpdate", (event) => { renderMarket(event.detail.data); }); uproot.onCustomEvent("OfferAccepted", (event) => { showNotification(`Your offer was accepted at ${event.detail.data}!`); }); ``` [See the double_auction example](https://github.com/mrpg/uproot-examples/tree/main/double_auction) ## Background tasks with `spawn` Sometimes you need work to continue after a `@live` method returns. Examples are calling an external API or running a loop that pushes updates every few seconds. `spawn` launches an async function in the background so it keeps running independently: ```python async def ask_llm(player): response = await call_api(player.question) player.answer = response send_to(player, response, event="Answer") class Question(Page): @live async def submit_question(page, player, text: str): player.question = text spawn(ask_llm(player)) # returns immediately; ask_llm keeps running return {"status": "thinking"} ``` The spawned task is supervised: Exceptions are logged instead of silently swallowed, and all tasks are cancelled when the server shuts down. Tasks do **not** survive server restarts. If your server restarts and you need the task again, re-launch it from the `restart()` function in your app module. ```python async def tick(session): while True: with session: session.counter += 1 send_to(session.players, session.counter) await asyncio.sleep(1) async def restart(): # Re-launch background tasks after a server restart from uproot.storage import Admin with Admin() as admin: for session in admin.sessions: if session.get("counter") is not None: spawn(tick(session)) ``` !!! warning Because spawned tasks run outside a page method, uproot does not auto-track mutations to lists and dicts. Wrap writes in a context manager: `with player as p:` or `with session as s:`. [See the continuous example](https://github.com/mrpg/uproot-examples/tree/main/continuous) · [chat_with_claude example](https://github.com/mrpg/uproot-examples/tree/main/chat_with_claude) ## Summary | Feature | Use case | |---------|----------| | `notify(sender, recipients, data)` | Broadcasting updates to participants | | `notify(..., event="Name")` | Named events for specific handlers | | `send_to(recipients, data)` | Server-initiated updates (background tasks) | | `uproot.onCustomEvent("Name", fn)` | Listening for named events | | `uproot.receive = fn` | Default handler for unnamed notifications | | `player.others_in_group` | All group members except sender | | `player.others_in_session` | All session members except sender | | `spawn(coroutine)` | Run a background task (see above) | --- Source: https://uproot.science/multiplayer/chat.md # Built-in chat uproot provides a built-in chat system for experiments where participants need to communicate. The chat handles message display, pseudonyms, and real-time updates automatically. ## Creating a chat Create a chat at the session or group level, typically in the `new_session` callback: ```python def new_session(session): session.chat = chat.create(session) ``` The `chat.create()` function returns a chat identifier that you store on the session for later use. [See the chat example](https://github.com/mrpg/uproot-examples/tree/main/chat) ## Adding players to a chat Add participants to the chat using `chat.add_player()`. This is typically done when they reach the chat page: ```python class ChatPage(Page): @classmethod async def before_once(page, player): chat.add_player(player.session.chat, player) ``` The `before_once` method ensures each player is added exactly once, even if they refresh the page. ### Assigning pseudonyms You can assign pseudonyms to protect participant identity: ```python chat.add_player( player.session.chat, player, pseudonym=f"Player {player.id}", ) ``` If no pseudonym is provided, an anonymous identifier is generated automatically. ## Displaying the chat Use the `chat()` template function to render the chat interface: ```html+jinja {% extends "Base.html" %} {% block main %} {{ chat(session.chat) }} {% endblock main %} ``` The chat widget provides: - a message display area showing all messages; - an input field for typing messages; - a send button; - real-time updates when others send messages; - visual distinction between your messages and others’. ## Session-level chat The simplest chat setup is session-wide, where all participants can see all messages: ```python def new_session(session): session.chat = chat.create(session) class ChatPage(Page): @classmethod async def before_once(page, player): chat.add_player( player.session.chat, player, pseudonym=f"Player {player.id}", ) page_order = [ ChatPage, ] ``` [See the chat example](https://github.com/mrpg/uproot-examples/tree/main/chat) ## Group-level chat For private communication within groups, create a chat per group in the `after_grouping` callback: ```python class GroupPlease(GroupCreatingWait): group_size = 2 @classmethod def after_grouping(page, group): group.chat = chat.create(group.session) for player in group.players: chat.add_player(group.chat, player) ``` Then display the group’s chat: ```html+jinja {{ chat(player.group.chat) }} ``` ## Multiple chats You can create multiple chat channels for different purposes: ```python def new_session(session): session.general_chat = chat.create(session) session.announcements = chat.create(session) # Admin-only channel ``` Display them on the same page or different pages: ```html+jinja

General discussion

Announcements

{{ chat(session.announcements) }} ``` ## Reacting to new messages Use `chat.on_message()` to register a callback that runs whenever a message is sent to a chat. This is useful for bots, automated responses, or recording-keeping logic. ```python async def on_chat_message(chat, player, message): if player is None: return # Message was sent programmatically, not by a participant # React to the message here def new_player(player): player.my_chat = chat.create(player.session) chat.add_player(player.my_chat, player) chat.on_message(player.my_chat, on_chat_message) ``` The callback receives: - `chat`: the `ModelIdentifier` of the chat; - `player`: the player who sent the message, or `None` if sent programmatically; - `message`: the message text. The callback is persistent: it is automatically restored when the server restarts. [See the chat example with callback](https://github.com/mrpg/uproot-examples/tree/main/chat) · [chat_with_claude example](https://github.com/mrpg/uproot-examples/tree/main/chat_with_claude) ## Chat API reference ### `chat.create(session)` Creates a new chat channel. ```python chat_id = chat.create(session) ``` Returns a `ModelIdentifier` that you store on the session or group. ### `chat.add_player(chat, player, pseudonym=None)` Adds a participant to the chat. ```python chat.add_player(session.chat, player) chat.add_player(session.chat, player, pseudonym="Alice") ``` ### `chat.messages(chat)` Returns all messages in the chat. ```python all_messages = chat.messages(session.chat) ``` ### `chat.players(chat)` Returns the list of players in the chat. ```python participants = chat.players(session.chat) ``` ### `chat.exists(chat)` Checks if a chat exists. ```python if chat.exists(session.chat): ... ``` ## Styling the chat The chat uses Bootstrap classes and can be customized with CSS. The main elements are: - `.uproot-chat`: Container for the entire chat widget; - `.messages-container`: the scrollable message area; - `.list-unstyled`: the message list. Example custom styling: ```css .messages-container { height: 400px; overflow-y: auto; } .uproot-chat .btn { min-width: 80px; } ``` ## Complete example Here is a complete session-level chat: ```python def new_session(session): session.chat = chat.create(session) class ChatHere(Page): @classmethod async def before_once(page, player): chat.add_player( player.session.chat, player, pseudonym=f"Player {player.id}", ) page_order = [ ChatHere, ] ``` Template (`ChatHere.html`): ```html+jinja {% extends "Base.html" %} {% block title %} Chat {% endblock title %} {% block main %} {{ chat(session.chat) }} {% endblock main %} ``` [See the full chat example](https://github.com/mrpg/uproot-examples/tree/main/chat) · [prisoners_dilemma_chat example](https://github.com/mrpg/uproot-examples/tree/main/prisoners_dilemma_chat) ## Summary | Function | Purpose | |----------|---------| | `chat.create(session)` | Create a new chat channel | | `chat.add_player(chat, player, pseudonym=...)` | Add a participant to the chat | | `chat.on_message(chat, callback)` | Register a callback for new messages | | `chat(chat_id)` | Template function to render the chat | | `chat.messages(chat)` | Get all messages | | `chat.players(chat)` | Get all participants | --- Source: https://uproot.science/advanced/timeouts.md # Page timeouts Timeouts automatically advance participants to the next page after a specified duration. Use them for timed tasks, real-effort experiments, or to keep participants moving through your study. ## Static timeout Set a fixed timeout in seconds as a class attribute: ```python class TimedTask(Page): timeout = 60 # Auto-advance after 60 seconds ``` When the timeout expires, the page submits automatically with whatever data has been entered. ## Dynamic timeout Use a method to calculate the timeout based on player state: ```python class AdaptiveTask(Page): @classmethod def timeout(page, player): # Faster participants get less time base_time = 120 bonus = player.correct_answers * 5 return base_time - bonus ``` The method receives `page` and `player` and returns the timeout in seconds. Return `None` to disable the timeout for that player. ## Handling timeout expiration The `timeout_reached` callback runs when the timeout expires: ```python class TimedQuiz(Page): timeout = 30 @classmethod def timeout_reached(page, player): player.timed_out = True player.score = 0 # Penalty for not answering in time ``` This callback runs before the page advances. Use it to: - Record that the participant timed out - Apply penalties or default values - Set flags for conditional logic later ## Timeouts and `may_proceed` A page with a [`may_proceed`](https://uproot.science/reference/page-methods.md#may_proceed) method keeps participants on the page until a condition holds. A timeout overrides this: once the deadline has passed, the page advances even if `may_proceed` returns `False`. This keeps [wait pages](https://uproot.science/multiplayer/synchronization.md) from hanging forever when time runs out. uproot counts a timeout as reached up to one second before the deadline. In that last second, the page only advances if `may_proceed` allows it. So if the next page relies on the deadline having passed, check the deadline in `may_proceed`: ```python class Negotiate(Page): @classmethod def timeout(page, player): from time import time return max(0, player.group.deadline - time()) @classmethod def may_proceed(page, player): from time import time return player.group.agreed or time() >= player.group.deadline ``` Without `may_proceed`, a participant can reach the next page up to one second before the deadline. To change this tolerance, set `upd.TIMEOUT_TOLERANCE` (in seconds) in `main.py`. ## Timeout spanning multiple pages For a shared timeout across several pages, store the deadline and calculate remaining time dynamically: ```python class InitializeTimeout(NoshowPage): @classmethod def after_always_once(page, player): from time import time player.deadline = time() + 60 # 60 seconds total player.failed = False class TimedPage(Page): @classmethod def timeout(page, player): from time import time return max(0, player.deadline - time()) @classmethod def timeout_reached(page, player): if not player.failed: player.failed = True class Task1(TimedPage): pass class Task2(TimedPage): pass class Task3(TimedPage): pass page_order = [ InitializeTimeout, Task1, Task2, Task3, Results, ] ``` All three task pages share the same 60-second deadline. If time runs out on any page, `player.failed` is set. [See the timeout_multipage example](https://github.com/mrpg/uproot-examples/tree/main/timeout_multipage) ## Timeouts with live methods Timeouts work well with live methods for real-effort tasks: ```python class Sumhunt(Page): timeout = 120 # 2 minutes to solve puzzles @live async def submit_answer(page, player, answer: int): if answer == player.correct_answer: player.score += 1 player.puzzle = generate_new_puzzle() return player.puzzle ``` The participant interacts via live methods until the timeout advances them. [See the sumhunt example](https://github.com/mrpg/uproot-examples/tree/main/sumhunt) · [encryption_task example](https://github.com/mrpg/uproot-examples/tree/main/encryption_task) ## Hiding the countdown display Sometimes participants should not see how much time is left, for example when time pressure is part of your design. To hide the countdown, override the `timeoutbox` block with an empty one in your page’s template: ```html+jinja {% extends "Base.html" %} {% block timeoutbox %}{% endblock timeoutbox %} {% block title %} Negotiation {% endblock title %} {% block main %}

Make your offer.

{% endblock main %} ``` The timeout still applies. Only the display is gone. ## Repositioning the countdown display uproot automatically shows a countdown timer in `#uproot-timeout`. To move it elsewhere on your page, relocate the `#uproot-time-remaining` element with JavaScript: ```html+jinja

Time remaining:

``` This moves the countdown into your custom container and removes the default wrapper. ## Checking timeout status in templates Access the timeout flag in your results template: ```html+jinja {% if player.timed_out %}

You ran out of time.

{% else %}

You completed the task in time.

{% endif %} ``` ## Advanced: JavaScript timeout API The `uproot` object exposes timeout state and events for custom interfaces. The countdown uses the monotonic `performance.now()` clock, not a Unix deadline. ### Reading timeout state The current state is available in the built-in Alpine store: ```javascript const timeout = Alpine.store("uproot").timeout; // { active, level, text, compact } ``` For lower-level access, use `uproot.pageTimeoutRemainingMs()` while a timeout is active. The `pageTimeoutStartMs` and `pageTimeoutDurationMs` properties are also available, but the Alpine store is the more stable interface. ### Timeout events Two custom events fire on `window`: ```javascript // Fires once when the timeout is set window.addEventListener("UprootInternalPageTimeoutSet", (event) => { console.log("Timeout started:", event.detail); }); // Fires every second during countdown window.addEventListener("UprootInternalPageTimeout", (event) => { updateCustomDisplay(event.detail); }); ``` ### Visual feedback classes The default `#uproot-timeout` element automatically changes its timeout level class based on the remaining time: | Remaining time | Class added | |----------------|-------------| | More than 60 seconds | `uproot-timeout-light` | | 15–60 seconds | `uproot-timeout-warning` | | Less than 15 seconds | `uproot-timeout-danger` | ### Custom countdown display Combine these APIs for a fully custom countdown: ```html+jinja

``` To hide the default display, override the `timeoutbox` block as shown in [Hiding the countdown display](#hiding-the-countdown-display). ## Summary | Feature | Purpose | |---------|---------| | `timeout = 60` | Static timeout in seconds | | `def timeout(page, player)` | Dynamic timeout calculation | | `def timeout_reached(page, player)` | Callback when timeout expires | | Return `None` from timeout | Disable timeout for that player | | `{% block timeoutbox %}{% endblock timeoutbox %}` | Hide the countdown display | | `Alpine.store("uproot").timeout` | JavaScript: current timeout state | | `UprootInternalPageTimeoutSet` | JavaScript: event when timeout starts | | `UprootInternalPageTimeout` | JavaScript: event every second | --- Source: https://uproot.science/advanced/dropouts.md # Handling dropouts In multiplayer experiments, participants may close their browser or lose their connection. uproot provides tools to detect dropouts and handle them gracefully. ## Automatic dropout detection Use `watch_for_dropout` to monitor a player and trigger a callback when they go offline: ```python def new_player(player): player.dropout = False watch_for_dropout(player, handle_dropout) async def handle_dropout(player): player.dropout = True move_to_end(player) ``` The watcher checks every few seconds whether the player’s browser is still connected. If the player has been offline for longer than the tolerance period (default: 30 seconds), the handler fires. [See the dropouts example](https://github.com/mrpg/uproot-examples/tree/main/dropouts) ## `watch_for_dropout` ```python watch_for_dropout(player, handler, tolerance=30.0) ``` | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `player` | player | — | The player to watch | | `handler` | async function | — | Called when dropout is detected | | `tolerance` | `float` | `30.0` | Seconds of inactivity before triggering | The handler receives the `player` as its argument. It can be an async function. Register the watcher in `new_player` so it starts monitoring as soon as the player joins. ## Moving dropouts to the end The most common response to a dropout is to move them to the end page: ```python async def handle_dropout(player): player.dropout = True move_to_end(player) ``` `move_to_end(player)` advances the player past all remaining pages. If they return, they will see the end page instead of being stuck on a wait page that blocks other players. ## Marking dropouts manually From the admin interface, select players and use the **Mark as dropout** action. This sets `player._uproot_dropout = True` and triggers the admin dropout flow. Programmatically: ```python from uproot.smithereens import mark_dropout mark_dropout(player.pid) ``` `mark_dropout` marks the player for the dropout watcher. Register a watcher if you want a handler to run; the function alone does not move the player or call the handler immediately. ## Handling dropouts in group experiments In multiplayer experiments, a dropout can block other group members at synchronization points. A single participant closing their browser, walking away, or losing connectivity can leave their partner staring at “waiting for other participants” indefinitely. A robust solution tracks dropout at the *group* level and handles three distinct dropout vectors: 1. **Browser disconnect:** The participant closes the tab or loses connectivity (`watch_for_dropout`). 2. **Page timeout:** The participant sits on a decision page without submitting (`timeout_reached`). 3. **Sync timeout:** One participant submits but their partner never arrives at the wait page (`timeout` on `SynchronizingWait`). ### The group-level drop pattern Use a boolean `group.dropped` flag as the single source of truth. When any dropout vector fires, mark the group and redirect all other members to a dedicated Dropped page: ```python class C: TIMEOUT = 60 # seconds to make a decision SYNC_TIMEOUT = 90 # seconds to wait at sync points def drop_group(group, culprit): group.dropped = True group.dropped_by = culprit.name for p in group.players: if p.name != culprit.name: with p as pp: move_to_page(pp, Dropped) ``` `drop_group` does three things: marks the group, records who caused the drop, and moves every *other* player to the Dropped page. The `with p as pp:` [context manager](https://uproot.science/building/data.md) is required here because you are mutating a player object from outside that player’s own page method. !!! warning "Guard against double-dropping" Multiple dropout vectors can fire for the same group (e.g., a browser disconnect triggers `watch_for_dropout` at the same moment a page timeout fires). Always check `if not group.get("dropped")` before calling `drop_group`. ### Registering watchers in `after_grouping` Register `watch_for_dropout` in `after_grouping`, not `new_player`, because the handler needs access to the group. When iterating `group.players` inside `after_grouping`, wrap each player in a context manager: ```python class GroupPlease(GroupCreatingWait): group_size = 2 @classmethod def after_grouping(page, group): group.dropped = False for player in group.players: player.timed_out = False with player: watch_for_dropout(player, handle_dropout) ``` The `with player:` block is needed because `after_grouping` receives the group, and iterating `group.players` yields player objects that require the context manager for uproot to track their mutations properly. ### The dropout handler The handler fires when a participant disconnects. It marks the player as timed out, drops the group if it has not been dropped already, and moves the disconnected player to the end: ```python async def handle_dropout(player): player.timed_out = True group = player.group if group is not None and not group.get("dropped"): drop_group(group, player) move_to_end(player) ``` ### Page timeouts on decision pages Add a [timeout](https://uproot.science/advanced/timeouts.md) to every decision page. When it expires, `timeout_reached` drops the group: ```python class Dilemma(Page): fields = dict( cooperate=RadioField( label="Do you wish to cooperate?", choices=[(True, "Yes"), (False, "No")], ), ) @classmethod def timeout(page, player): return C.TIMEOUT @classmethod def timeout_reached(page, player): player.timed_out = True if not player.group.get("dropped"): drop_group(player.group, player) @classmethod def before_once(page, player): if player.group.get("dropped"): move_to_page(player, Dropped) ``` The `before_once` guard at the bottom is equally important: If the group was already dropped (because the *other* player timed out or disconnected), this player should not see the decision page at all. Instead, they get redirected to `Dropped` immediately. !!! tip If you have many decision pages, you can avoid repeating these three methods on each one. See [Reducing repetition with a mixin class](#appendix-reducing-repetition-with-a-mixin-class) at the end of this page. ### Sync timeout A `SynchronizingWait` page can also time out. This covers the case where one player submits their decision but the other never arrives: ```python class Sync(SynchronizingWait): @classmethod def timeout(page, player): return C.SYNC_TIMEOUT @classmethod def timeout_reached(page, player): if not player.group.get("dropped"): player.group.dropped = True player.group.dropped_by = "sync_timeout" @classmethod def all_here(page, group): if group.get("dropped"): return for player in group.players: # ... compute and assign payoffs ... ``` The guard in `all_here` prevents payoff calculation for dropped groups. ### The Dropped page Create a terminal page that tells participants what happened. Distinguish between the player who timed out and their partner: ```html+jinja {% extends "Base.html" %} {% block title %}Time expired{% endblock title %} {% block main %} {% if player.timed_out %}

You did not make a choice in time. Your pair has been removed from this round.

{% else %}

Your partner did not make a choice in time. Your pair has been removed from this round.

{% endif %} {% endblock main %} ``` In your Python code, the Dropped page moves the player to the end after they see the message: ```python class Dropped(Page): @classmethod def after_once(page, player): move_to_end(player) ``` Add Dropped to the end of `page_order`: ```python page_order = [ GroupPlease, Dilemma, Sync, Results, Dropped, ] ``` ### Guarding downstream pages Every page after grouping should check the drop flag and redirect. Add a `before_once` guard to your Results page (and any other post-sync page). (If you have many such pages, see the [mixin appendix](#appendix-reducing-repetition-with-a-mixin-class).) ```python class Results(Page): @classmethod def before_once(page, player): if player.group.get("dropped"): move_to_page(player, Dropped) ``` ### Excluding dropped groups from data If your experiment uses a `digest` function, skip dropped groups so they do not contaminate the summary: ```python def digest(session): dropped_pairs = 0 for group in session.groups(app=__name__): if group.get("dropped"): dropped_pairs += 1 continue # ... normal payoff analysis ... return { # ... "dropped_pairs": dropped_pairs, } ``` If your experiment uses a `pipeline` function, include `timed_out` and `dropped` so you can filter in downstream analysis: ```python def pipeline(session, data=None): rows = [] for group in session.groups(app=__name__): for player in group.players: player_data = player.within(app=__name__) rows.append({ # ... other fields ... "timed_out": player_data.get("timed_out"), "dropped": group.get("dropped"), }) return rows ``` ### Showing dropout counts in the admin digest If your experiment uses an `AdminDigest.html` template, display a warning when groups were dropped: ```html+jinja {% if dropped_pairs > 0 %}

{{ dropped_pairs }} pair{{ "s" if dropped_pairs != 1 }} dropped due to timeout.

{% endif %} ``` ## Adjusting tolerance Lower the tolerance for fast-paced experiments where delays are critical: ```python watch_for_dropout(player, handle_dropout, tolerance=10.0) ``` Increase it for experiments where participants may be reading long instructions: ```python watch_for_dropout(player, handle_dropout, tolerance=120.0) ``` ## Checking dropout status in templates ```html+jinja {% if player.dropout %}

This player has been marked as a dropout.

{% endif %} ``` ## Summary | Feature | Purpose | |---------|---------| | `watch_for_dropout(player, handler, tolerance=30.0)` | Monitor a player for disconnection | | `move_to_end(player)` | Move player past all remaining pages | | `move_to_page(player, PageClass)` | Redirect a player to a specific page | | `mark_dropout(pid)` | Manually mark a player as dropout | | `player._uproot_dropout` | Internal dropout flag | | Admin: Mark as dropout | Manual dropout from admin interface | | `group.dropped` | Group-level flag for tracking dropped groups | | `with p as pp:` / `with player:` | Context manager for cross-player mutations | | `group.get("dropped")` | Safe check that returns `None` if not set | | `before_once` guard | Redirect dropped players away from normal pages | --- ## Appendix: reducing repetition with a mixin class !!! note "Optional—for readers comfortable with Python classes" This section shows a convenience pattern for experiments with many decision pages. It is not required. If you only have one or two decision pages, adding the methods directly (as shown above) is simpler and perfectly fine. In the group dropout pattern above, every decision page needs the same three methods: `timeout`, `timeout_reached`, and `before_once`. If your experiment has several decision pages, repeating those methods on each one gets tedious. Python lets you factor them out into a **[mixin class](https://docs.python.org/3/tutorial/classes.html#multiple-inheritance)**. This is a small class that bundles reusable methods and can be combined with `Page` (or any other page type) via [multiple inheritance](https://realpython.com/inheritance-composition-python/#mixing-features-with-mixin-classes). ### Defining the mixin ```python class DroppableMixin: """Adds timeout + dropout guard to any page.""" @classmethod def timeout(page, player): return C.TIMEOUT @classmethod def timeout_reached(page, player): player.timed_out = True if not player.group.get("dropped"): drop_group(player.group, player) @classmethod def before_once(page, player): if player.group.get("dropped"): move_to_page(player, Dropped) ``` ### Using the mixin Place `DroppableMixin` *before* `Page` in the class definition. Python checks classes left to right, so methods from `DroppableMixin` take precedence over defaults in `Page`: ```python class Dilemma(DroppableMixin, Page): fields = dict( cooperate=RadioField( label="Do you wish to cooperate?", choices=[(True, "Yes"), (False, "No")], ), ) class Negotiation(DroppableMixin, Page): fields = dict( offer=IntegerField(label="Your offer", min=0, max=100), ) class Results(DroppableMixin, Page): @classmethod def templatevars(page, player): return dict(payoff=player.payoff) ``` Each page now inherits the timeout and dropout guard automatically. You still define `fields`, `templatevars`, and any other page-specific methods as usual; they sit alongside the inherited ones without conflict. ### Overriding a single method If one page needs a different timeout, override just that method. The other two (`timeout_reached` and `before_once`) are still inherited from the mixin: ```python class LongDecision(DroppableMixin, Page): @classmethod def timeout(page, player): return 120 # more time for this page ``` ### Pages that only need the guard Some pages (like `Results`) do not need a timeout—they have no form to submit. The mixin still works: `timeout` returning a value on a page without fields is harmless. But if you prefer, you can skip the mixin and add just the guard directly: ```python class Results(Page): @classmethod def before_once(page, player): if player.group.get("dropped"): move_to_page(player, Dropped) ``` Either approach is fine. The mixin is most valuable when you have many decision pages that all share the same timeout and dropout logic. --- Source: https://uproot.science/advanced/uploads.md # File uploads uproot supports file uploads from participants using `FileField`. Uploaded files are handled as stealth fields: They are not stored in the database automatically, giving you full control over how to process them. ## Basic file upload Add a `FileField` to your page: ```python class Upload(Page): fields = dict( cv=FileField(label="Please upload your curriculum vitæ."), ) @classmethod async def handle_stealth_fields(page, player, data): cv = data["cv"] contents = await cv.read() player.file_name = cv.filename player.file_size = len(contents) ``` `FileField` is always treated as a stealth field. The uploaded file is passed to `handle_stealth_fields` as a [Starlette UploadFile](https://www.starlette.io/requests/#request-files) object. [See the upload example](https://github.com/mrpg/uproot-examples/tree/main/upload) ## The UploadFile object The uploaded file has these attributes: | Attribute | Type | Description | |-----------|------|-------------| | `filename` | `str` | Original filename | | `size` | `int` | File size in bytes | | `content_type` | `str` | MIME type (e.g., `image/png`) | And this method: | Method | Returns | Description | |--------|---------|-------------| | `await file.read()` | `bytes` | Read the full file contents | ## Storing uploaded files Since uploads are stealth fields, you decide where to store the data. Common approaches: ### Save to disk ```python @classmethod async def handle_stealth_fields(page, player, data): photo = data["photo"] if photo.size > 0: contents = await photo.read() from pathlib import Path path = Path("uploads") / ( f"{player.session.name}_{player.name}_{uuid()}" f"{Path(photo.filename or '').suffix.lower()}" ) path.parent.mkdir(parents=True, exist_ok=True) with path.open("wb") as f: f.write(contents) player.photo_path = str(path) ``` ### Store metadata only ```python @classmethod async def handle_stealth_fields(page, player, data): doc = data["document"] player.doc_name = doc.filename player.doc_size = doc.size player.doc_type = doc.content_type ``` ## Validating uploads Return error messages from `handle_stealth_fields` to reject the submission: ```python @classmethod async def handle_stealth_fields(page, player, data): photo = data["photo"] if photo.size == 0: return "Please select a file" if photo.size > 5_000_000: return "File too large (max 5 MB)" if photo.content_type not in ("image/png", "image/jpeg"): return "Only PNG and JPEG files are accepted" contents = await photo.read() player.photo_size = len(contents) ``` ## Combining uploads with regular fields You can mix file uploads with regular fields on the same page. Regular fields are saved automatically; the file field goes through `handle_stealth_fields`: ```python class UploadPage(Page): fields = dict( participant_name=StringField(label="Your name"), photo=FileField(label="Upload a photo"), ) @classmethod async def handle_stealth_fields(page, player, data): photo = data["photo"] if photo.size > 0: contents = await photo.read() player.photo_name = photo.filename ``` The `participant_name` field saves to `player.participant_name` automatically. `player.name` is reserved for uproot’s generated player name. The `photo` field is handled separately. ## Rendering in templates Use the standard field rendering: ```html+jinja {% extends "Base.html" %} {% block main %} {{ field(form.cv) }} {% endblock main %} ``` Or render all fields at once: ```html+jinja {{ fields() }} ``` ## Summary | Feature | Purpose | |---------|---------| | `FileField(label=...)` | File upload field | | `handle_stealth_fields(page, player, data)` | Process uploaded files | | `await file.read()` | Get file contents as bytes | | `file.filename` | Original filename | | `file.size` | File size in bytes | | `file.content_type` | MIME type | | Return a string from handler | Validation error message | --- Source: https://uproot.science/advanced/models.md # Custom data models Models provide structured, append-only data storage beyond the standard player/group/session fields. Use them for ordered collections of entries like transaction logs, auction bids, or any data that accumulates over time. !!! note The built-in [chat system](https://uproot.science/multiplayer/chat.md) is built on top of models. For chat functionality, use the chat API directly. ## Creating a model Create a model in a session, typically in `new_session`: ```python from uproot.models import create_model def new_session(session): session.offers = create_model(session) ``` `create_model` returns a `ModelIdentifier` that you store on the session (or group) for later use. ## Defining entry types Define the structure of your entries using the `Entry` metaclass: ```python from uproot.models import Entry from uproot.types import PlayerIdentifier class Offer(metaclass=Entry): player: PlayerIdentifier price: float quantity: int ``` Entry classes are immutable dataclasses. The `id` field name is reserved. Fields with types `PlayerIdentifier`, `SessionIdentifier`, `GroupIdentifier`, or `ModelIdentifier` are auto-filled when using `add_entry`. ## Adding entries Use `add_entry` to add an entry to a model. Identifier fields matching the player’s session, group, or player ID are filled automatically: ```python from uproot.models import add_entry @live async def post_offer(page, player, price: float, quantity: int): add_entry(player.session.offers, player, Offer, price=price, quantity=quantity) ``` The first argument is the model identifier, the second is the player (used for auto-filling identifier fields), and the third is the entry type. Remaining keyword arguments fill the entry’s fields. Each entry is timestamped and assigned a UUID. ### Raw entries To add an entry without auto-filling, use `add_raw_entry`: ```python from uproot.models import add_raw_entry add_raw_entry(session.offers, {"event": "started", "detail": "phase 2"}) ``` ## Retrieving entries ### All entries ```python from uproot.models import get_entries entries = get_entries(session.offers, Offer) for uuid, timestamp, offer in entries: print(f"{offer.player} offered {offer.price} at {timestamp}") ``` `get_entries` returns a list of `(UUID, float, entry)` tuples, ordered by time. ### Filtered entries ```python from uproot.models import filter_entries # Filter by field values cheap_offers = filter_entries(session.offers, Offer, price=10.0) # Filter by predicate large_offers = filter_entries( session.offers, Offer, predicate=lambda o: o.quantity > 100, ) # Filter by entry UUID specific = filter_entries(session.offers, Offer, id=some_uuid) ``` ### Latest entry ```python from uproot.models import get_latest_entry uuid, timestamp, latest = get_latest_entry(session.offers, Offer) ``` ### Single field Read a single field from the model’s storage: ```python from uproot.models import get_field value = get_field(session.offers, "some_field") ``` ## Checking existence ```python from uproot.models import model_exists if model_exists(session.offers): ... ``` ## Example: auction log A complete example using models to track bids in an auction: ```python from uproot.models import Entry, create_model, add_entry, get_entries, get_latest_entry from uproot.types import PlayerIdentifier class Bid(metaclass=Entry): player: PlayerIdentifier amount: float def new_session(session): session.auction = create_model(session) class Auction(Page): @live async def place_bid(page, player, amount: float): add_entry(player.session.auction, player, Bid, amount=amount) # Get all bids bids = get_entries(player.session.auction, Bid) # Return current highest if bids: _, _, highest = max(bids, key=lambda b: b[2].amount) return {"highest": highest.amount, "total_bids": len(bids)} return {"highest": 0, "total_bids": 0} ``` ## Summary | Function | Purpose | |----------|---------| | `create_model(session)` | Create a new model, returns `ModelIdentifier` | | `add_entry(mid, player, EntryType, **fields)` | Add entry with auto-filled identifiers | | `add_raw_entry(mid, entry)` | Add entry without auto-filling | | `get_entries(mid, EntryType)` | Get all entries as `(UUID, time, entry)` tuples | | `filter_entries(mid, EntryType, **filters)` | Get filtered entries | | `get_latest_entry(mid, EntryType)` | Get most recent entry | | `get_field(mid, field_name)` | Read a field from model storage | | `model_exists(mid)` | Check if a model exists | --- Source: https://uproot.science/advanced/settings-forms.md # Custom settings forms When an experimenter creates a session, they can adjust the config’s default [session settings](https://uproot.science/building/data.md#session-settings) by editing raw JSON in the admin interface. Raw JSON is flexible, but it is also easy to get wrong: a mistyped key or a string where a list is expected, and the session runs with the wrong parameters. An app can replace that JSON editor with its own settings form. If your app folder contains a file named `AdminSettings.html`, the admin’s new-session page shows your form instead of the JSON editor whenever a config containing your app is selected. !!! warning "Super advanced" This is one of the most advanced features in uproot. You will write raw HTML, [Jinja](https://jinja.palletsprojects.com/) template code, and [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) by hand. uproot’s [form fields](https://uproot.science/building/forms.md) are not available here. Most apps are perfectly fine with the JSON editor. This page assumes you have read [Session settings](https://uproot.science/building/data.md#session-settings). ## A minimal example Suppose your app defines a default number of rounds in its constants class and reads it from the session settings: ```python class C: DEFAULT_ROUNDS = 3 ``` Create `AdminSettings.html` next to your app’s `__init__.py`: ```html+jinja {% set n_rounds = settings.get("n_rounds", C.DEFAULT_ROUNDS) %}

Number of rounds

``` Three things happen here: 1. The fragment prefills the input from `settings` (the config’s defaults), falling back to `C.DEFAULT_ROUNDS`, so the form always starts at the values the session would get anyway. 2. The inline script registers a *reader* function for this editor with `registerSessionSettingsEditor`. 3. When the experimenter clicks **Create session**, the reader runs. It validates the input and returns an object whose keys are merged into the session settings. Throwing an error blocks session creation and shows the error message to the experimenter. This is your validation mechanism. The fragment is not a full page: do not extend `Base.html` or any other template. Write only the form markup and its script. Admin pages load [Bootstrap 5](https://getbootstrap.com/docs/5.3/forms/overview/), so classes like `form-control` and `form-label` work as expected. ## Where uproot looks - `your_app/AdminSettings.html`: This form is used for every config that includes `your_app`. If a config contains several apps with such a file, all their forms are shown, stacked in the config’s app order. - `AdminSettings.html` at the project root: This is a project-level form that takes over for *all* configs; app-level fragments are then ignored. - A fragment that renders to only whitespace is skipped, so you can opt out per config with a Jinja `{% if %}` around the whole file. - Configs without any fragment keep the plain JSON editor. ## Template variables Fragments are rendered server-side when the new-session page loads, once per config. They receive: | Variable | Meaning | |----------|---------| | `config` | Name of the config this rendering belongs to | | `apps` | List of app names in that config | | `appname` | The app the fragment belongs to (`None` for a project-level fragment) | | `settings` | The config’s default settings, as declared via `load_config(..., settings={...})` | | `editor_id`{ .text-nowrap } | Unique ID for this editor—use it as your root element’s `id` and pass it to `registerSessionSettingsEditor` | | `C` | The app’s constants class (app fragments only) | | `appstatic` | URL helper for the app’s static files (app fragments only) | !!! warning The same app can appear in several configs, so your fragment may be rendered several times into the same admin page. Never hard-code element IDs; always derive them from `editor_id`, as in the example above. ## The reader function The reader you register runs when the experimenter submits the form. It receives one argument, an object with - `config`: the selected config’s name; and - `settings`: the settings collected so far: the config’s defaults, already merged with the contributions of readers registered before yours. Return a JSON-serializable object; its keys are merged over those settings. Keys your form does not touch keep their default values. Return `undefined` to contribute nothing. Throw an `Error` with a human-readable message to abort session creation and display the message. ## What the experimenter sees When a config with a custom form is selected, the **Keep default settings** checkbox starts unchecked and the form is shown, prefilled with the defaults. Checking the box hides the form and uses the config’s defaults unchanged. For such configs, the custom form fully replaces the JSON editor. There is no raw JSON fallback in the UI. If a fragment raises an error while rendering, or a config’s default settings are not a JSON object, the new-session page shows a red error message for that config instead of a form, and the config falls back to the JSON editor. The full traceback lands in the server log. ## Complete example The double auction example ships a settings form covering eight settings, including comma-separated integer lists and values that may be either a scalar or one entry per round: [See AdminSettings.html in the double_auction example](https://github.com/mrpg/uproot-examples/blob/main/double_auction/AdminSettings.html) --- Source: https://uproot.science/running/admin.md # The admin interface The admin interface lets you create and manage sessions, monitor participant progress, and intervene during experiments. ## Accessing the admin The admin is available at `/admin/` on your server. During development: ``` http://127.0.0.1:8000/admin/ ``` ### Authentication uproot lets you sign in with a secret login link or a password. The default setup in [`main.py`](https://uproot.science/getting-started/project-structure.md#the-mainpy-file) supports both: ```python upd.ADMINS["admin"] = upd.auto_login() ``` When `UPROOT_ADMIN_PASSWORD` is unset or empty and `admin` is the only admin account, uproot prints an auto-login URL when the server starts: ``` Auto login: http://127.0.0.1:8000/admin/login/#aBcDeFgHiJkL... ``` The link authenticates you as `admin` using a cryptographically random secret token. You can use it locally or in production. Keep the link and server logs private, and use HTTPS for [public deployments](https://uproot.science/running/deployment.md). #### Password login For password login, set `UPROOT_ADMIN_PASSWORD`, an **environment variable** (a named startup setting). Use your hosting provider’s secret settings or a `.env` file in the project directory: ```dotenv UPROOT_ADMIN_PASSWORD='replace-with-a-long-random-password' ``` Replace the example value with a long, unique password. uproot rejects passwords shorter than five characters at startup. Keep `.env` out of Git and restrict access to it. uproot loads it automatically using [python-dotenv](https://bbc2.github.io/python-dotenv/#getting-started); existing environment variables take precedence. Restart the server, then sign in at `/admin/` as `admin`. A non-empty password replaces the login link; `main.py` stays unchanged. #### Multiple admin accounts Adding or renaming accounts disables the printed login link. Give each account its own password by replacing the single-account assignment in `main.py`: ```python import os upd.ADMINS["admin"] = os.environ["UPROOT_ADMIN_PASSWORD"] upd.ADMINS["researcher"] = os.environ["UPROOT_RESEARCHER_PASSWORD"] ``` [`os.environ`](https://docs.python.org/3/library/os.html#os.environ) reads environment variables. Set both variables to different, long passwords as above. A missing variable stops startup with a `KeyError`; set it and restart. Use the first assignment alone to require password login for a single account. ## Dashboard The dashboard (`/admin/dashboard/`) shows an overview of active sessions and rooms. From here you can navigate to any session or room. ## Creating sessions Navigate to **Sessions** → **New session** to create a session: 1. **Config:** Select which experiment config to run. 2. **Number of players:** How many player slots to create. 3. **Settings (JSON):** Optional JSON object for session settings (accessible via `session.settings`); apps can replace this JSON editor with a [custom settings form](https://uproot.science/advanced/settings-forms.md). 4. **Custom session name:** Optional (auto-generated if omitted). 5. **Custom player names:** Optional (auto-generated if omitted). 6. **Simulate responses:** If enabled, the app’s `simulate.js` file runs on every player page load (see [App testing](#app-testing) below). After creation, each player gets a unique URL: ``` https://your-server.com/p/{session_name}/{player_name}/ ``` ## Session management The session detail page (`/admin/session/{sname}/`) is your control center during an experiment. ### Player monitor The session page shows all players with their current status: - **current page:** which page each player is on; - **online status:** whether the player is currently connected; - **progress:** how far through the experiment each player is. ### Player actions Select one or more players and use these actions: | Action | What it does | |--------|-------------| | **Advance** | Move selected players forward one page | | **Revert** | Move selected players back one page, but not into an earlier round or app (see below) | | **Move to end** | Skip selected players to the end of the experiment | | **Reload** | Force a page reload in selected players’ browsers | | **Send message** | Display a message on selected players’ screens | | **Mark as dropout** | Flag selected players as dropouts | | **Redirect** | Send selected players to an external URL | | **Set fields** | Set arbitrary field values on selected players | | **Group/ungroup** | Manually create or dissolve groups | | **Run `new_player`** | Re-run the `new_player` callback for selected players | !!! note "Reverting stops at the start of rounds and apps" **Revert** cannot take players back into an earlier round of [`Rounds` or `Repeat`](https://uproot.science/building/operators.md#rounds), into an earlier app, or out of the end of the experiment. uproot does not count `player.round` back down or switch `player.app` back, so anything players entered after such a revert would be saved under the wrong round or app. If any selected player would cross such a boundary, uproot shows “The action failed” and moves none of the selected players. The server log names the player and the boundary. ### Session controls | Control | What it does | |---------|-------------| | **Toggle active** | Pause/resume the session (inactive sessions reject new page loads) | | **Toggle testing** | Mark the session as a test run (useful for filtering data later) | | **Update description** | Add a note about the session | | **Update settings** | Modify session settings (JSON) | | **Run `new_session`** | Re-run the `new_session` callback | ### Data browser Click **View data** on the session page to browse all stored data in a table view. Each player’s fields are shown with their current values, timestamps, and the code location that set each value. You can filter the table by app, by [block](https://uproot.science/building/operators.md#blocks), and by round. ### Downloading data Click **Download data** on the session page to download the session’s complete data as a single ZIP archive. See [Exporting data](https://uproot.science/running/export.md) for what is inside and how to analyze it. ### Page times Download a CSV of page visit times showing when each player entered and left each page (available under *Other data* on the **Download data** page). Useful for measuring response times. ### Digest If your app defines `digest(session)`, the digest view shows its output. A list of rows is a common return value. Pair it with `AdminDigest.html` in the app directory: that file must contain **only** a `main` block (do not extend `Base.html`). Lists and other non-dict values are available as `data`: ```html+jinja {% block main %}

{{ data | length }} groups so far.

{% endblock main %} ``` If `digest()` returns a dictionary, its keys become template variables instead. For example, `return {"groups": rows}` makes the rows available as `groups`. [See the prisoners_dilemma_repeated example for a digest implementation](https://github.com/mrpg/uproot-examples/tree/main/prisoners_dilemma_repeated) ### Pipeline If your app defines `pipeline(session, data)`, the admin can run it from the session page. Return a list of dictionaries to get a downloadable table (one row per dict): ```python def pipeline(session, data=None): rows = [] for group in session.groups(app=__name__): p1, p2 = group.players p1_data = p1.within(app=__name__) p2_data = p2.within(app=__name__) rows.append(dict( group=group.name, p1=p1.name, p1_cooperate=p1_data.get("cooperate"), p2=p2.name, p2_cooperate=p2_data.get("cooperate"), )) return rows ``` [`player.within()`](https://uproot.science/building/results.md#using-playerwithin) selects values recorded in this app. Using `.get()` keeps the pipeline usable before every participant has submitted a decision. uproot always calls `pipeline(session=session, data=data)`. The admin (or [REST API](https://uproot.science/reference/admin-api.md)) can post JSON that is passed through as `data`; without a JSON body, `data` is `None`. The admin provides a built-in JSON input for this. To show app-specific instructions or status above the pipeline buttons, add `AdminPipeline.html` with a `main` block only. [See pipeline in the prisoners_dilemma_fancy example](https://github.com/mrpg/uproot-examples/tree/main/prisoners_dilemma_fancy) · [prediction_market example](https://github.com/mrpg/uproot-examples/tree/main/prediction_market) ## Managing rooms Navigate to **Rooms** to see all rooms, separated into open and closed sections. See [Rooms](https://uproot.science/running/rooms.md) for details on room configuration. From a room’s admin page you can: - see which participants are waiting in the room (with live label tracking); - create a session with pre-assigned player slots; - edit room settings (config, labels, capacity) when no session is associated. When a session is associated, the room’s admin page shows: - **room status:** open/closed, capacity, and join mode (free join or restricted); - **close room**/**Reopen room:** stop or resume accepting new participants without affecting the running session (see [Closing and reopening a room](https://uproot.science/running/rooms.md#closing-and-reopening-a-room)); - **disassociate:** unlink the session, so the room can be reused. ## Admin chat The admin chat lets experimenters communicate directly with individual participants during a running session. Open it from the session detail page by clicking the chat icon next to a player. Features: - **Per-player channels:** Each participant gets a private conversation with the experimenter. - **Enable/disable replies:** Control whether the participant can write back or only receive messages. - **Participant-side widget:** A floating chat button appears on the participant’s screen when the admin sends a message. - **Real-time updates:** Messages appear instantly on both sides via WebSocket. Participants see a small button in the bottom-right corner. Messages from the experimenter appear in a pop-up chat window. Whether the participant can reply is controlled by the toggle in the admin view. !!! note Admin chat channels are created automatically the first time the admin sends a message to a participant. No setup is required in your app code. ## App testing uproot supports automated page interactions via a `simulate.js` file in each app. When a session is created with the **Simulate responses** option enabled, `simulate.js` runs on every player page load. This lets you verify that your experiment works end-to-end without manually clicking through as a participant. The fastest way to run a simulated session is from the command line: [`uproot start`](https://uproot.science/reference/cli.md#uproot-start) with the `--simulate` flag starts the server with a room whose session has simulation enabled. ```console uv run uproot start myconfig --simulate ``` Open the printed room link and watch the app play itself. ### Writing simulate.js When you create a new project with `uproot setup`, a template `simulate.js` is generated automatically. Register a handler with `uproot.simulate.on()` and use the simulation helpers to fill fields and submit: ```javascript uproot.simulate.on("my_app/Decision", (sim) => { sim.choose("choice", sim.random(["A", "B"])).submit(); }); ``` The page key passed to `uproot.simulate.on()` is `"app_name/PageClassName"`. | Helper | What it does | |--------|----------------| | `sim.fill(name, value)` or `sim.fill({age: 30, name: "Ada"})` | Set one or several input values | | `sim.choose(name, value)` | Select a radio button or dropdown option | | `sim.check(name)` / `sim.uncheck(name)` | Toggle a checkbox | | `sim.oneOf(name, values)` | Choose a random value from an array | | `sim.chooseAnyRadio()` | Pick a random radio button on the page | | `sim.random(array)` | Return a random element | | `sim.integer(min, max)` | Return a random integer in `[min, max]` | | `sim.submit()` | Submit the page | | `sim.value(name)` | Read the current value | | `sim.element(name)` / `sim.field(name)` | Find a DOM element | The setters (`fill`, `choose`, `check`, `uncheck`, `select`, `oneOf`, and `chooseAnyRadio`) and `submit` return `sim`, so you can chain them. Lookup helpers such as `value`, `element`, and `field` return the requested value or DOM element instead. Pages with no fields can just call `sim.submit()`. !!! warning Simulation is session-level and permanent. Once a session is created with simulation enabled, it cannot be disabled for that session. Create a new session without the option to run without simulation. [See simulate.js in the prisoners_dilemma example](https://github.com/mrpg/uproot-examples/tree/main/prisoners_dilemma) ## Server status The status page (`/admin/status/`) shows: - database size; - installed package versions; - environment variables; - active authentication sessions. ### Announcements The status page also has a button that checks whether the uproot developers have posted important announcements, such as security fixes, for your version. Check regularly while you run studies. Once the server has been running for a minute, the dashboard and status page remind you if you have never checked or your last check was over a week ago. Click “Dismiss nudge” on the status page to silence the reminder for ten years. uproot never contacts uproot.science on its own—only when you click this button, click “Submit praise” in the footer, or run [`uproot announcements`](https://uproot.science/reference/cli.md#uproot-announcements). Participants’ browsers never contact it at all (see [Why uproot?](https://uproot.science/why-uproot.md#your-participants-talk-only-to-your-server)). If your server must never make outside connections, for example in an isolated lab network, switch these features off in `main.py`: ```python upd.UPSTREAM = False ``` The server then never contacts uproot.science, and the announcement and praise buttons and reminders disappear from the admin interface. You then need to check for announcements some other way, for instance by visiting [uproot.science](https://uproot.science/) now and then. ## Database dump Download a complete database dump from `/admin/dump/`. This is equivalent to running `uproot dump` from the CLI. ## Summary | Page | URL | Purpose | |------|-----|---------| | Dashboard | `/admin/dashboard/` | Overview of sessions and rooms | | Sessions | `/admin/sessions/` | List all sessions | | New session | `/admin/sessions/new/` | Create a session | | Session detail | `/admin/session/{sname}/` | Monitor and control a session | | Admin chat | `/admin/session/{sname}/chat/` | Chat with individual participants | | Data browser | `/admin/session/{sname}/viewdata/`{ .text-nowrap } | Browse session data | | Data download | `/admin/session/{sname}/data/` | Download session data as a ZIP archive | | Rooms | `/admin/rooms/` | List all rooms | | Status | `/admin/status/` | Server information | --- Source: https://uproot.science/running/rooms.md # Sessions and rooms Sessions and rooms are the two concepts for managing how participants access your experiment. ## Sessions A **session** is a running instance of an experiment config, containing players and their data. Each session has a unique session name (a short random string by default) and is associated with exactly one config. ### Creating a session directly From the admin interface, navigate to **Sessions** and create a new session by selecting a config and specifying the number of players. This gives you a session with pre-created player slots that you can distribute manually. Each pre-created player gets a unique URL of the form: ``` https://your-server.com/p/{session_name}/{player_name}/ ``` You can share these URLs with participants individually. This approach works well for small experiments or when you want to assign specific participants to specific slots. ### Session initialization A session is initialized the first time a player loads their first page. Initialization runs the `new_session` callback in each app (if defined), followed by `new_player` for that player. If you created the session manually with pre-created players, you can also trigger initialization explicitly via the admin API using the `run_new_session` and `run_new_player` endpoints. ## Rooms A **room** is a gateway that controls how participants enter a session. Instead of distributing individual player URLs, you can give all participants the same room URL: ``` https://your-server.com/room/{room_name}/ ``` The room handles everything: waiting for the experiment to start, validating credentials, creating player slots, and redirecting participants to their session. ### Creating a room Navigate to **Rooms** in the admin interface and create a new room. A room has several optional settings: - **Config**: Which experiment config to run. - **Labels**: Access codes that restrict who can join. - **Capacity**: A maximum number of players. - **Open**: Whether the room is currently accepting participants. You can also create a room from code in your project’s `main.py` by appending to `DEFAULT_ROOMS`: ```python import uproot.deployment as upd from uproot.rooms import room upd.DEFAULT_ROOMS.append( room( "my_room", config="my_experiment", labels=["ALPHA", "BRAVO", "CHARLIE"], capacity=20, open=True, ) ) ``` Rooms defined this way are created automatically when the server starts. ### Quick rooms from the command line During development, creating a room by hand just to test a config is tedious. The [`uproot start`](https://uproot.science/reference/cli.md#uproot-start) command does it in one step: ```console uv run uproot start my_experiment ``` This creates an open room named `quick1` (then `quick2`, and so on), creates a session for the config, starts the server, and prints the room URL. Open the URL in one browser tab per participant. Add `--simulate` to enable [simulated responses](https://uproot.science/running/admin.md#app-testing) for the session. Quick rooms are ordinary rooms: they appear under **Rooms** in the admin, and everything on this page applies to them. ### Room lifecycle A room acts as a finite-state machine with two main states: **Waiting (closed)** The room is in waiting state when any of the following are true: - `open` is `False` - No config is associated with the room - Both of the above Participants who visit a waiting room see a “Please wait” page. This page maintains a WebSocket connection to the server so it can advance automatically when the room opens. Participants do not need to refresh. **Accepting (open)** When `open` is `True` and a config is set, the room begins accepting participants. Two things happen: 1. If no session exists yet, one is automatically created from the room’s config when the first participant arrives. 2. Participants are added to the session (subject to label and capacity checks). After joining, participants are redirected to their player URL and begin the experiment. ### Starting a session in a room From a room’s admin page, you can start a session in two ways: **Let participants join on their own.** Set the room to open with a config. A session is created automatically when the first participant arrives, and subsequent participants join the same session. This is the most common approach. **Pre-create a session with players.** Use the “Create session” form on the room’s admin page. Specify a config and the number of players. The session is created with player slots, the room opens, and waiting participants are notified via WebSocket. Pre-created player slots are claimed on a first-come, first-served basis. When a session is started in a room (either way), the `r.start(roomname)` signal fires, which wakes all WebSocket connections on the waiting page. Participants’ browsers automatically submit the join form. ### Closing and reopening a room You can close a room at any time to stop accepting new participants—even while a session is active. Closing a room does **not** affect the running session or its current players; it only prevents new participants from joining. From the room’s admin page, use the **Close room** button. To resume accepting participants into the same session, use **Reopen room**. This is useful when: - You have enough participants and want to prevent latecomers from joining. - You need to temporarily pause enrollment while checking on the experiment. - You want to control exactly when new participants can enter. Via the API, use [`PATCH /admin/api/v1/rooms/{roomname}/open/`](https://uproot.science/reference/admin-api.md#patch-adminapiv1roomsroomnameopen) with `{"open": false}` to close or `{"open": true}` to reopen. #### Closing vs. capacity Closing a room and setting a capacity are two different mechanisms: - **Capacity** limits how many players can join. Once the limit is reached, new participants see a “Room full” page. The room remains open and will accept participants again if capacity is freed up or increased. - **Closing** shuts the door entirely. No new participants can join regardless of available capacity. Participants who visit a closed room see a “Please wait” page. Use capacity when you want a fixed maximum group size. Use closing when you want manual control over *when* participants can enter, independent of how many have already joined. ### Disassociating and reusing rooms A room can only have one session at a time. To reuse a room for a new session, first **disassociate** the current session. This unlinks the session from the room and resets the room’s state so new participants can wait again. Room settings (config, labels, capacity) can only be edited when no session is associated. ### Labels (access codes) Labels normally restrict room access to a predefined set of participants. Each participant must enter a valid label (access code) to join. You can also require a code without defining the allowed values in advance. ```python upd.DEFAULT_ROOMS.append( room( "my_room", config="my_experiment", labels=["ALPHA", "BRAVO", "CHARLIE"], ) ) ``` When labels are set: - Participants see a “Welcome” page with an access code input field. - The entered label is validated against the room’s label list. - Invalid labels are rejected with an error message. - Labels must use only the characters `A-Za-z0-9-._` and be at most 128 characters long. Pass `labels=[]` (an empty list) to accept **any** non-empty access code, without listing codes in advance. To load codes from a text file (one label per line; `#` starts a comment), use `from_file`: ```python from uproot.rooms import room, from_file upd.DEFAULT_ROOMS.append( room("lab", config="my_experiment", labels=from_file("labels.txt")) ) ``` After entering a valid label, participants wait for the room to open (if it is not already open). Once the room opens, they are automatically redirected. If a participant enters a label that has already been used by another player in the session, they are redirected to that existing player’s URL. This means a participant can rejoin using the same label if they lose their connection. ### Eagerly accepted labels *If* your room does not require labels, uproot will still eagerly accept labels that are provided using the `?label=` URL parameter. You could use that feature as follows: ``` https://your-server.com/room/{room_name}/?label=MY_LABEL ``` This is useful for physical labs (where `MY_LABEL` may be `01` to `32`, the number of cubicles), and online platforms, such as [Prolific](https://prolific.com/) IDs. For Prolific, a room with `labels=[]` works even better. See [Running on Prolific](https://uproot.science/running/prolific.md). ### Labels and capacity When a non-empty label list is set but no explicit capacity is configured, the room’s effective capacity equals the number of labels. This means each label can be used by exactly one participant. The special `labels=[]` mode has no implicit capacity; set `capacity=` as well if you need a limit. If you set both labels and an explicit capacity, the capacity value takes precedence. For example, you could have 100 labels but a capacity of 50, meaning only the first 50 valid labels will be accepted. ### Capacity Capacity sets the maximum number of players that can join a room’s session. When the session is full, new participants see a “Room full” page. ```python upd.DEFAULT_ROOMS.append( room( "my_room", config="my_experiment", capacity=30, ) ) ``` ### How capacity is enforced A participant can join a room’s session if any of the following conditions are true: 1. **The room is freejoin:** `labels` is `None` or `[]`, and no capacity is set, so participants can join without limit. 2. **The session has room:** The current number of players is below the capacity. 3. **A free slot exists:**: A pre-created player slot that has not been claimed yet. Free slots bypass the capacity check, so pre-created players can always be claimed. This means capacity primarily controls *growth*: It prevents new player slots from being created beyond the limit. It does not prevent participants from claiming pre-created slots, even if the number of pre-created slots exceeds the capacity. ### Capacity and manual session creation When you create a session in a room with pre-created players, you can check the **"Set room capacity to number of players"** option. This sets the room’s capacity equal to the number of pre-created players, preventing any additional participants from joining beyond the pre-created slots. Without that option, the room’s original capacity setting (if any) remains. Pre-created slots can always be claimed, but new slots are only created up to the capacity. This implies: if you create a session with *n* players, but uncheck “Set room capacity to number of players,” your session can keep growing until the room’s capacity is reached. If the capacity is infinite, the session will be able to grow indefinitely. **Rooms are the only method to create new player slots in a session.** ### Freejoin rooms A room with the default `labels=None` and no capacity is a **freejoin** room. There is no limit on how many participants can join, and every visitor gets a new player slot in the session. This is useful for large-scale experiments where you want to accept as many participants as possible. The `labels=[]` mode with no capacity is also unlimited, but each visitor must enter a non-empty code. Reusing a code returns to the player slot that already has that code. ### The room WebSocket When participants are on the waiting page, the browser opens a WebSocket connection to the server. This connection serves two purposes: 1. **Instant notification**: When the room opens, a `RoomStarted` event is sent over the WebSocket, and the browser automatically submits the join form. Participants do not need to refresh. 2. **Presence tracking**: The server tracks which participants are online in the room’s waiting area. The admin can see this on the room’s admin page. The WebSocket connection uses a heartbeat mechanism to stay alive. If a participant closes the page, they are marked as offline. --- Source: https://uproot.science/running/prolific.md # Running on Prolific [Prolific](https://www.prolific.com/) is a platform for recruiting online participants. Prolific sends each participant to a URL you provide, and when they finish, they come back to Prolific with a *completion code* that tells Prolific to pay them. uproot needs very little setup for this: one room, one URL parameter, and one link at the end of your experiment. This page assumes you have read [Sessions and rooms](https://uproot.science/running/rooms.md) and know how to create a session in [the admin interface](https://uproot.science/running/admin.md). ## The setup at a glance 1. Create a room with `labels=[]` and no capacity, in the admin interface or in `main.py`. 2. In the admin, create a session in that room with **0 players** and put your completion code in the session settings. This opens the room. 3. Give Prolific the room URL, with the participant’s Prolific ID in `?label=`. 4. End your experiment with a “Finish study” link that sends participants to Prolific with the completion code. Each step is explained below. ## Step 1: Create the room You can create the room in the admin interface or in your project’s `main.py`. Both give you the same room. === "Admin interface" Go to **Rooms** in the admin and create a new room: - **Room name:** for example, `my_study`. - **Associate with a particular config:** check this and select your config. - **Start this config immediately:** uncheck this. It is checked by default (see below for why). - **Use labels/Access Codes:** check this, but leave the **Labels** box **empty**. - **Limit capacity of resulting session:** leave this unchecked. === "main.py" ```python upd.DEFAULT_ROOMS.append( room( "my_study", config="my_experiment", labels=[], open=False, ) ) ``` Rooms defined this way are created automatically when the server starts. An empty label list (`labels=[]`) means “every participant needs a label, and any non-empty label is accepted.” No capacity is set, so the room has no upper limit. Every participant who arrives gets a new player slot in the session. The room starts out closed. You open it in Step 2 by creating the session. Until then, anyone who visits the room URL sees a waiting page. If the room were already open, the first visitor would make uproot create a session automatically, without the completion code you are about to enter. ### Why `labels=[]` and not the default A room with the default `labels=None` would also accept everyone, and it would also store a `?label=` it finds in the URL (see [Eagerly accepted labels](https://uproot.science/running/rooms.md#eagerly-accepted-labels)). But `labels=[]` is the better choice for Prolific, for two reasons: - **Every player gets a Prolific ID.** If the label is missing from the URL (for example, because the participant copied the link by hand), uproot shows a page that asks for an access code instead of letting the participant in anonymously. You never end up with a player you cannot match to a Prolific submission. - **Participants cannot start twice.** If someone opens the study link again—after closing the tab, after a crash, or on a different device—uproot sees the same label and sends them back to their existing player slot. They continue where they left off instead of starting over in a fresh slot. Prolific IDs consist only of letters and digits, so they are valid labels (labels may contain `A-Za-z0-9-._`, up to 128 characters). ### Why no capacity It is tempting to set `capacity` to the number of places in your Prolific study. Do not do that. On Prolific, participants regularly return a study or time out, and Prolific then offers their place to someone new. The returned participant’s player slot still counts toward the room’s capacity, so a capacity equal to your number of places would lock out the replacements. Let Prolific control how many people take part. If you need to stop admissions, [close the room](https://uproot.science/running/rooms.md#closing-and-reopening-a-room) instead. ## Step 2: Create a session with 0 players On the room’s admin page, use the “Create session” form: - **Number of players:** `0`. Player slots are created as participants arrive, so you do not need any in advance. - **Keep default settings:** uncheck this. It is checked by default, and the **Settings** box appears only once you uncheck it. - **Settings:** your completion code, which you copy from your study’s page on Prolific: ```json {"completion_code": "C1ABC2DE"} ``` - **“Set room capacity to number of players”:** **uncheck** this. It is checked by default. Creating the session opens the room, so participants can join from now on. !!! warning "Do not check “Set room capacity to number of players”" With 0 players, this option sets the room’s capacity to 0. Every participant then sees a “Room full” page, and nobody can join. If this has already happened, go to the room’s admin page, open **Actions**, uncheck **Limit capacity**, and click **Set**. This removes the limit while the session keeps running. You can do the same via the [admin REST API](https://uproot.science/reference/admin-api.md#patch-adminapiv1roomsroomnamecapacity). Why create the session by hand instead of letting the room create one automatically? Because the admin form lets you enter [session settings](https://uproot.science/building/data.md#session-settings). Keeping the completion code in the session settings, rather than in your code, has two advantages: the code never ends up in a public Git repository, and you can run several Prolific studies (each with its own code) from the same project. If you mistype the code, fix it on the session page with **Change settings**. If you prefer, you can instead give the code as a default via [`load_config(..., settings={"completion_code": "C1ABC2DE"})`](https://uproot.science/getting-started/project-structure.md) and let the room create the session automatically when the first participant arrives. ## Step 3: Give Prolific the study URL In your Prolific study, enter the room URL as the study URL, and choose the option to [record Prolific IDs via URL parameters](https://researcher-help.prolific.com/en/articles/445178-what-survey-experimental-software-is-compatible-with-prolific). Prolific suggests a parameter named `PROLIFIC_PID`. Rename it to `label`: ``` https://your-server.com/room/my_study/?label={{%PROLIFIC_PID%}}&STUDY_ID={{%STUDY_ID%}}&SESSION_ID={{%SESSION_ID%}} ``` Prolific replaces `{{%PROLIFIC_PID%}}` with each participant’s ID. uproot reads only `label`. The `STUDY_ID` and `SESSION_ID` parameters are harmless, but uproot does not store them, so you can also drop them. Open the URL yourself with a made-up label, such as `?label=TEST1`, to check that everything works before you publish the study. Your test player appears in the session like any other player. ## Step 4: Send participants back to Prolific [Prolific’s completion URL](https://researcher-help.prolific.com/en/articles/445178-what-survey-experimental-software-is-compatible-with-prolific) has the form `https://app.prolific.com/submissions/complete?cc=YOUR_CODE`. Put a link to it on the last page of your experiment: ```html+jinja {% extends "Base.html" %} {% block main %}

Thank you for taking part!

Finish study

{% endblock main %} {% set buttons = False %} ``` The participant clicks the link, lands on Prolific, and their submission is marked as complete. Note `.get('completion_code', 'NOCODE')`: if you forget to set the code, or test the app on its own (via its `~app` config, which has [no settings](https://uproot.science/getting-started/project-structure.md)), the page still works. Prolific then receives the code `NOCODE`, which it does not recognize, so you notice the mistake and can review those submissions by hand. !!! note "Put the link on the last page" The participant should click “Finish study” only after uproot has saved all their data. Put the link on a page after your last form, not on a page with form fields, because a link does not submit the form. ## Working with the data Every player’s Prolific ID is stored as their `label`. When you [export your data](https://uproot.science/running/export.md), the `label` column lets you [match your experimental data to Prolific’s demographic data](https://researcher-help.prolific.com/en/articles/445210-matching-data-between-prolific-and-your-external-study-software). The label check works within one session only. If the same person could take part in two of your studies (for example, a pilot and the main study, each with its own room and session), use [Prolific’s filter that excludes participants of previous studies](https://researcher-help.prolific.com/en/articles/445164-how-can-i-prevent-specific-participants-from-accessing-my-study). ## Advanced: bonus payments and screen-outs The two recipes below need a bit more code. They are good tasks for a coding agent (such as Claude Code or Codex): describe your experiment and point the agent at this page. ### Bonus payments [Prolific’s bulk bonus form](https://researcher-help.prolific.com/en/articles/445233-how-do-i-send-bonus-payments) takes one line per participant: their Prolific ID and bonus amount, separated by a comma. uproot stores the Prolific ID as `player.label`, so you do not need anything from Prolific to build these lines. Suppose your app saves each participant’s bonus as `player.bonus`. A [pipeline](https://uproot.science/running/admin.md#pipeline) exports the participant IDs and amounts: ```python def pipeline(session, data=None): rows = [] for player in session.players: bonus = player.within(app=__name__).get("bonus") if player.label and bonus: rows.append(dict(prolific_id=player.label, amount=f"{bonus:.2f}")) return rows ``` Run the pipeline from the session page in the admin and download its table. In Prolific’s **Bulk actions** → **Bulk bonus payment**, paste one line per bonus as `,`, without a header row. Amounts are in your study’s currency. ### Screen-outs Sometimes participants should leave early, for example because they do not consent or fail an attention check. Prolific lets you define [several completion codes per study](https://researcher-help.prolific.com/en/articles/445170-custom-completion-codes), each with its own action (such as approving the submission, or asking the participant to return it). Put all codes in the session settings: ```json {"completion_code": "C1ABC2DE", "screenout_code": "C9XYZ8WV"} ``` If your app saves the outcome as `player.passed_attention_check`, pick the right code on the final page: ```html+jinja {% if player.passed_attention_check %} {% set cc = session.settings.get("completion_code", "NOCODE") %} {% else %} {% set cc = session.settings.get("screenout_code", "NOCODE") %} {% endif %} Finish study ``` To send screened-out participants to the final page right away, skip the remaining pages with a [`show`](https://uproot.science/building/pages.md) method, or use [`move_to_page`](https://uproot.science/reference/api.md#move_to_page) to send them to that page. --- Source: https://uproot.science/running/export.md # Exporting data uproot stores every piece of data your experiment collects in an [append-only log](https://uproot.science/building/data.md). Nothing is ever overwritten or lost. When you download your data, you do not have to pick and choose: you always get a single ZIP archive (the *data briefcase*) that contains your session’s complete data in all key formats, ready for Excel, R, or Python. This page shows you how to download that ZIP and how to analyze its contents. If you want to automate exports, work with the REST API, or analyze the database directly in Python, see [Advanced data access](https://uproot.science/running/export-advanced.md). ## Downloading your data On a session’s page in the admin interface, click **Download data**. You will see a short form: - **Latest × Field(s):** This adds an extra format with one row per player per grouping you specify (for example, one row per player per `round`). You can uncheck this if your study does not make use of multiple apps or rounds. Leave it checked if you are not sure; this format encompasses the “latest” format. - **File type:** **CSV** (opens in Excel and every stats package) or **JSONL** (preserves data types; see [CSV or JSONL?](#csv-or-jsonl) below). - **Apply reasonable filters:** This is checked by default. It cleans up uproot-internal fields so your data focuses on what your experiment actually collected. Click **Download** and you will receive one ZIP file named after the session and the current date, for example `mysession_2026-07-04_1412.zip`. ## What’s inside the ZIP Unpacking the ZIP gives you a single folder named after your session: ``` mysession/ ├── README.txt ← explains the contents, right inside the ZIP ├── DATA_DICTIONARY.json ← defines the !-prefixed columns ├── page_times.csv ← when each player entered/left each page ├── SHA256SUMS ← checksums for verifying all other files ├── latest/ │ ├── player.csv │ ├── group.csv │ └── session.csv ├── sparse/ │ ├── player.csv │ ├── group.csv │ └── session.csv └── ultralong/ ├── player.csv ├── group.csv └── session.csv ``` If you check **Latest × Field(s)**, there is one more folder, named after your grouping variable(s). With the default grouping variables (`app`, `block`, and `round`), it is `latest_by_app_block_round/`. Each subfolder contains the same data in a different *format* (explained below). Within each format, the data is split into one file per kind of storage: | File | Contains | |------|----------| | `player.csv` | Data stored on players; usually what you want | | `group.csv` | Data stored on groups (only if your session has groups) | | `session.csv` | Session-level data | | `model.csv` | [Custom data models](https://uproot.science/advanced/models.md) (only if your apps use them) | Each file only has columns for fields that actually occur in that kind of storage, so player files are not cluttered with session-level columns and vice versa. !!! tip "In a hurry?" **`latest/player.csv`** or **`latest_by_…/player.csv`** is the file most people want: one row per participant, one column per field, showing each field’s final value (at the end of each round when grouping by `round`). ## The three formats Every briefcase contains the same underlying data at three levels of detail: ### “Latest”: one row per player One row per storage (e.g., per player), showing the most recent value of every field. This is the most compact format and what you will typically use for analysis if your study does not involve multiple apps or multiple rounds. #### “Latest × Field(s)”: one row per player per level of your grouping variable(s) If you enable **Latest × Field(s)**, the `latest_by_…/` folder contains one row per player *per combination of your grouping variable(s)*—for example, each participant’s state at the end of each round. This is ideal for panel-style analyses. By default, uproot groups by `app`, `block`, and `round`. This gives you one row per participant for every round of every app and [block](https://uproot.science/building/operators.md#blocks). Apps without rounds get one row each, showing the participant’s state at the end of that app. !!! note Grouped snapshots include every field known at that point in time (except `page_order` with [reasonable filters](#reasonable-filters)). The grouping variables determine *when* snapshots are taken, not which columns they carry. Fields set before the grouping variable appear in the output as expected. ### “Sparse”: one row per change, one column per field Each row represents a single change. Every field has its own column, and only the field that changed at that moment is filled in. This produces a wide but mostly empty table. Useful when you want to reconstruct *how* values evolved but still prefer one column per field. ### “Ultralong”: the raw event log One row per field change, in full detail. Every time a field’s value was set, there is a row recording what changed, when, and where in the code. This is the most detailed format and preserves the complete history. Use it for temporal analyses, audits, or debugging. ## Understanding the columns Columns that start with `!` come from uproot itself; they sort to the front and can never clash with your own field names. In `ultralong` files you will find all of them: | Column | Description | |--------|-------------| | `!storage` | Which storage this row belongs to (e.g., `player/mysession/9wpsj`) | | `!field` | Field name | | `!time` | Unix timestamp of the change | | `!seq` | Sequence number of the change (for exact ordering) | | `!context` | Code location that made the change | | `!unavailable`{ .text-nowrap } | Whether this row marks a deletion (a tombstone) | | `!data` | The value | `latest` files just have `!storage`, `!time`, and `!seq` (the time and sequence of the most recent change reflected in the row), followed by one column per field. The full machine-readable definitions live in `DATA_DICTIONARY.json` inside the briefcase. The last part of `!storage` is the participant’s uproot name. For instance, `player/mysession/9wpsj` is participant `9wpsj` in session `mysession`. ## Reasonable filters The **Apply reasonable filters** option (on by default) cleans up uproot-internal fields: - It renames `_uproot_group` to `group` (with values like `group/mysession/g1`, matching the `!storage` column of `group.csv`; this is handy for merging, see below). When a participant leaves a group—for example, when they reach the next app’s `GroupCreatingWait` page—`group` becomes empty until they join a new one. - It renames `_uproot_session` to `session`. - In `group.csv` and `session.csv`, it renames `_uproot_players` to `players`: a list of the members, with values like `player/mysession/9wpsj`. - In `session.csv`, it renames `_uproot_groups` to `groups`: a list of the session’s groups, with values like `group/mysession/g1`. - It keeps `_uproot_dropout` and `_uproot_settings`. - It removes all other internal `_uproot_*` fields. - It leaves `page_order` out of `latest_by_…/`, where it would repeat every page in every row. It stays in the other formats, and `page_times` tells you which page each participant saw when. Turn filters off only if you need to inspect uproot’s internal bookkeeping. ## CSV or JSONL? **CSV** is the safe default: It opens directly in Excel, R, Python, Stata, and everything else. Booleans are written as `TRUE`/`FALSE`, missing values as empty cells, and lists or dictionaries as JSON text within the cell. **JSONL** ([JSON Lines](https://jsonlines.org/): one JSON object per line) is worth choosing when your data contains lists, dictionaries, or mixed types. Unlike CSV, it keeps the distinction between numbers, strings, Booleans, and nested structures. That is, no more guessing whether `"1"` is a number or a string. Both pandas and R read it with one line of code. Whichever you choose, the briefcase has the same structure—just with `.jsonl` files instead of `.csv` files. ## Analyzing your data You do not even have to unpack the ZIP: Both R and Python can read individual files straight out of the archive, entirely in memory. The examples below assume you downloaded `mysession_2026-07-04_1412.zip` and that the session is called `mysession`. (Adjust the names accordingly. Of course, if you prefer, you can also unpack the ZIP and read the files from disk; the reading code is the same, minus the ZIP part.) === "R" With base R, `unz()` opens a single file inside a ZIP as a connection—no extraction needed: ```r zipfile <- "mysession_2026-07-04_1412.zip" players <- read.csv(unz(zipfile, "mysession/latest/player.csv"), check.names = FALSE) ``` (`check.names = FALSE` keeps column names like `!storage` intact instead of mangling them to `X.storage`.) With **readr/dplyr**, `read_csv()` accepts the same connection and preserves column names by default: ```r library(readr) players <- read_csv(unz(zipfile, "mysession/latest/player.csv")) ``` With **data.table**, let `fread()` pull the file out of the ZIP via the `unzip` command: ```r library(data.table) players <- fread(cmd = paste("unzip -p", zipfile, "mysession/latest/player.csv")) ``` Column names starting with `!` are perfectly legal in R; just wrap them in backticks: ```r library(dplyr) players |> select(`!storage`, payoff) |> arrange(desc(payoff)) ``` **Merging players with their groups.** With filters applied, each player’s `group` column matches the `!storage` column of `group.csv`: ```r library(dplyr) players <- read_csv(unz(zipfile, "mysession/latest/player.csv")) groups <- read_csv(unz(zipfile, "mysession/latest/group.csv")) full <- left_join(players, groups, by = c("group" = "!storage"), suffix = c("", ".group")) ``` Or with data.table: ```r full <- merge(players, groups, by.x = "group", by.y = "!storage", suffixes = c("", ".group")) ``` **JSONL** briefcases work exactly the same way, with jsonlite: ```r library(jsonlite) players <- stream_in(unz(zipfile, "mysession/latest/player.jsonl")) ``` === "Python" Python’s built-in `zipfile` module opens a single file inside a ZIP (no extraction needed), and **pandas** reads directly from it: ```python import zipfile import pandas as pd with zipfile.ZipFile("mysession_2026-07-04_1412.zip") as zf: with zf.open("mysession/latest/player.csv") as f: players = pd.read_csv(f) ``` Column names starting with `!` require bracket notation: ```python players[["!storage", "payoff"]].sort_values("payoff", ascending=False) ``` **Merging players with their groups.** With filters applied, each player’s `group` column matches the `!storage` column of `group.csv`: ```python with zipfile.ZipFile("mysession_2026-07-04_1412.zip") as zf: with zf.open("mysession/latest/player.csv") as f: players = pd.read_csv(f) with zf.open("mysession/latest/group.csv") as f: groups = pd.read_csv(f) full = players.merge(groups, how="left", left_on="group", right_on="!storage", suffixes=("", "_group")) ``` **JSONL** briefcases need just one extra argument: ```python with zipfile.ZipFile("mysession_2026-07-04_1412.zip") as zf: with zf.open("mysession/latest/player.jsonl") as f: players = pd.read_json(f, lines=True) ``` ## Verifying your download Every briefcase includes a `SHA256SUMS` file listing the checksum of every other file in the archive. To confirm that nothing was corrupted or modified—for instance, before archiving data for publication—run this inside the unpacked folder: ```bash cd mysession sha256sum -c SHA256SUMS ``` (On macOS, use `shasum -a 256 -c SHA256SUMS`.) ## Page times Every briefcase includes a `page_times.csv` (or `.jsonl`) file tracking when each player entered and left each page. This is useful for measuring response times. Its columns are: | Column | Description | |--------|-------------| | `sname` | Session name | | `uname` | Player name | | `show_page`{ .text-nowrap } | Page index | | `page_name` | Page class name | | `entered` | Unix timestamp when the player entered the page | | `left` | Unix timestamp when the player left the page | | `context` | Round/context information | Page times are derived from the players’ `show_page` and `page_order` histories. ## Going further For everything beyond the download button, see [Advanced data access](https://uproot.science/running/export-advanced.md): - Downloading briefcases automatically via the [REST API](https://uproot.science/reference/admin-api.md) - Streaming JSONL exports - Full database backups with `uproot dump` - Offline analysis of the database in Python with `uproot.read` --- Source: https://uproot.science/running/export-advanced.md # Advanced data access This page covers programmatic and low-level ways to get at your data: automated exports via the REST API, streaming JSONL, full database backups, and offline analysis with `uproot.read`. If you just want to download and analyze your data, start with [Exporting data](https://uproot.science/running/export.md). ## Export via the REST API Use the [Admin REST API](https://uproot.science/reference/admin-api.md) for programmatic access. All endpoints used on this page require Bearer token authentication. ### Downloading the briefcase `GET /admin/api/v1/sessions/{sname}/data/export/` returns the same ZIP briefcase as the admin interface’s **Download data** page: ```bash curl -OJ -H "Authorization: Bearer YOUR_TOKEN" \ "https://your-server.com/admin/api/v1/sessions/mysession/data/export/" ``` (`-OJ` saves the file under the name suggested by the server, e.g. `mysession.zip`.) Query parameters: | Parameter | Values | Default | Description | |-----------|--------|---------|-------------| | `filetype` | `csv`, `jsonl` | `csv` | File type used inside the briefcase | | `gvar` | field names (repeatable) | — | Adds a grouped latest format (e.g., `latest_by_round/`) | | `filters` | `true`, `false` | `true` | Apply reasonable filters | For example, a JSONL briefcase with an extra format grouped by app and round: ```bash curl -OJ -H "Authorization: Bearer YOUR_TOKEN" \ "https://your-server.com/admin/api/v1/sessions/mysession/data/export/?filetype=jsonl&gvar=app&gvar=round" ``` !!! note The `uproot api` CLI command prints responses as text, so it is not suited to binary downloads like the briefcase. Use `curl` (or any HTTP client) for this endpoint. ### Streaming JSONL `GET /admin/api/v1/sessions/{sname}/data/jsonl/` streams a single format as JSONL—no ZIP, no splitting by storage kind. This is useful for piping data directly into other tools, or when sessions are large: ```bash # Raw event log (default) uproot api sessions/mysession/data/jsonl > mysession.jsonl # Latest state, with filters curl -H "Authorization: Bearer YOUR_TOKEN" \ "https://your-server.com/admin/api/v1/sessions/mysession/data/jsonl/?format=latest&filters=true" ``` Query parameters: | Parameter | Values | Default | Description | |-----------|--------|---------|-------------| | `format` | `ultralong`, `sparse`, `latest` | `ultralong` | Export format | | `gvar` | field names (repeatable) | — | Group-by variables (for `latest`) | | `filters` | `true`, `false` | `false` | Apply [reasonable filters](https://uproot.science/running/export.md#reasonable-filters) (with `gvar`, this also leaves out `page_order`) | ## Database dumps For a complete backup of all data, use the dump/restore commands: ```bash # Dump the entire database to a file uproot dump --file backup.msgpack.gz # Restore from a dump uproot restore --file backup.msgpack.gz ``` You can also download a dump from the admin interface at `/admin/dump/`, or via the REST API: ```bash curl -o backup.msgpack.gz -H "Authorization: Bearer YOUR_TOKEN" \ "https://your-server.com/admin/api/v1/database/dump/" ``` !!! note Database dumps contain all sessions and all data. Use the briefcase or JSONL endpoints for per-session exports. ## Offline analysis with uproot.read For analysis in Python (e.g., in a Jupyter notebook), you can open an `uproot.sqlite3` database file directly and navigate it using the same Storage objects the server uses: ```python from uproot.read import read db = read("uproot.sqlite3") for session in db.sessions: for group in session.groups: for player in group.players: with player: print(player.name, player.label, player.payoff) db.close() ``` The `Database` object supports context managers: ```python with read("uproot.sqlite3") as db: session = db.session("my_session") with session: for player in session.players: with player: print(player.choice) ``` ### Plain-row helpers For analysis scripts that need regular dictionaries rather than live Storage objects, use the plain-row methods. Each returns a list of dictionaries with identifier columns plus any extra fields you request. Missing fields become `None`. ```python with read("uproot.sqlite3") as db: players = db.player_rows(["label", "role", "payoff"]) memberships = db.membership_rows() ``` | Method | Identifier columns | Extra fields | |--------|--------------------|--------------| | `db.session_rows(fields)`{ .text-nowrap } | `session` | Yes | | `db.group_rows(fields)` | `session`, `group` | Yes | | `db.player_rows(fields)` | `session`, `uname` | Yes | | `db.membership_rows()` | `session`, `group`, `uname`, `position` | No | To grab all four tables at once, use `snapshot`: ```python with read("uproot.sqlite3") as db: snap = db.snapshot( session_fields=["sid"], group_fields=["round"], player_fields=["label", "role", "payoff"], ) print(snap.sessions) # list of dicts print(snap.groups) print(snap.players) print(snap.memberships) print(snap.as_dict()) # single dict with all four tables ``` ### Database API | Method/Property | Description | |-----------------|-------------| | `db.sessions` | All sessions in the database | | `db.session(sname)` | Get a session by name | | `db.group(sname, gname)` | Get a group by session and group name | | `db.player(sname, uname)` | Get a player by session and username | | `db.session_rows(fields)`{ .text-nowrap } | Plain dictionaries, one per session | | `db.group_rows(fields)` | Plain dictionaries, one per group | | `db.player_rows(fields)` | Plain dictionaries, one per player | | `db.membership_rows()` | Plain dictionaries, one per group membership | | `db.snapshot(...)` | All four plain-row tables as a `Snapshot` | | `db.close()` | Close the database | !!! note `uproot.read` gives you the same Storage objects used at runtime. You can access `player.group`, `player.session`, `group.players`, and all virtual fields. Remember to use `with player:` (or `with session:`, etc.) before reading attributes. The plain-row helpers handle context management internally. ## Summary | Method | Use case | |--------|----------| | [ZIP briefcase](https://uproot.science/running/export.md) | Per-session data for analysis (admin UI or API) | | Streaming JSONL endpoint | Piping one format into other tools | | `uproot.read` | Offline analysis in Python/Jupyter | | `uproot dump` | Full database backup | --- Source: https://uproot.science/running/deployment.md # Deployment This page explains how to make your experiment accessible over the internet. It assumes you have [installed uproot and created a project](https://uproot.science/getting-started/installation.md). Choose the option that suits you: 1. **[Use Cloudflare](#option-1-use-cloudflare).** If you have a computer with a stable, high-bandwidth internet connection, run uproot there and let Cloudflare connect participants to it. The same approach also works on a VPS. 2. **[Self-host on your own VPS](#option-2-self-host-on-your-own-vps).** A virtual private server (VPS) is a rented computer that you manage remotely. Use nginx and Let’s Encrypt for full control over your web server and HTTPS setup—no third-party service touches participant traffic. 3. **[Use a hosting service](#option-3-use-a-hosting-service).** Deploy to Fly.io, Render, or Heroku using the instructions below. ## Option 1: Use Cloudflare [Cloudflare Tunnel](https://developers.cloudflare.com/tunnel/) connects your computer to Cloudflare, which forwards participants’ requests to uproot. Your experiment and database stay on your computer. Cloudflare provides the public [HTTPS](https://developer.mozilla.org/en-US/docs/Glossary/HTTPS) address, which encrypts the browser connection, without requiring you to configure nginx, certificates, or port forwarding on your router. ### Try it for free [TryCloudflare](https://try.cloudflare.com/) gives you a temporary public address for free, without a Cloudflare account or your own domain name. First, [install `cloudflared` for your operating system](https://github.com/cloudflare/cloudflared#installing-cloudflared) and set an [admin password](https://uproot.science/running/admin.md#authentication). In your project directory, [start uproot](https://uproot.science/reference/cli.md#uproot-run): ```bash uv run uproot run ``` In a second terminal on the same computer, run: ```bash cloudflared tunnel --url http://localhost:8000 ``` The command prints a public address such as `https://random-words.trycloudflare.com`. Leave the tunnel running. In your project’s [`.env` file](https://uproot.science/getting-started/project-structure.md), add or update this line, replacing the example with the address you received: ```text UPROOT_ORIGIN=https://random-words.trycloudflare.com ``` This tells uproot which public address to use for links. uproot reads `.env` at startup, so stop it with ++ctrl+c++ in its terminal, then run `uv run uproot run` again to pick up the change. Open the public address followed by `/admin/`, sign in, and create a [session or room](https://uproot.science/running/rooms.md). Share the participant links from the admin interface. Keep both terminals running and prevent the computer from sleeping while anyone is using the experiment. Its internet connection needs sufficient **upload bandwidth**, since your computer sends the experiment’s pages and files to participants. If you restart the Quick Tunnel, update `UPROOT_ORIGIN` with its new address and restart uproot before sharing new links. !!! note "For testing" Cloudflare’s [Quick Tunnels](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/trycloudflare/) are intended for testing and development. They have no uptime guarantee and a limit of 200 simultaneous requests. For collecting research data, use a permanent tunnel as described below. ### Use a permanent address for production For a stable address such as `https://study.example.com`, follow Cloudflare’s [tunnel setup guide](https://developers.cloudflare.com/tunnel/get-started/). You need a Cloudflare account and a domain name added to it. Give the tunnel a name, choose your public hostname, and point it to `http://localhost:8000`. Update `UPROOT_ORIGIN` to the public HTTPS address and restart uproot. Permanent tunnels and custom hostnames are available on the free plan. For production use, we recommend a [paid Cloudflare plan](https://www.cloudflare.com/plans/pro/) for additional security features. See [current plans and pricing](https://www.cloudflare.com/plans/) before choosing. Payment is not required simply to name a tunnel or use your own domain. Cloudflare publishes [GDPR safeguards and a data processing addendum](https://www.cloudflare.com/trust-hub/gdpr/). Because participant traffic passes through Cloudflare, your institution should assess whether the setup meets your study’s data-protection requirements. !!! tip "Use the same setup on a VPS" You can also install uproot and `cloudflared` on a VPS and point a permanent tunnel to `http://localhost:8000` there. Cloudflare handles public HTTPS, saving you the nginx and Let’s Encrypt setup, and your experiment and database live on the VPS so your personal computer can be switched off. 1. Follow the [VPS setup guide](https://uproot.science/running/vps-setup.md) to prepare the server. 2. [Start uproot on boot](https://uproot.science/running/vps-setup.md#start-uproot-on-boot) with a systemd service. 3. Use Cloudflare’s tunnel setup in place of the nginx and certificate steps. 4. [Run `cloudflared` as a service](https://developers.cloudflare.com/tunnel/get-started/#create-a-tunnel) so it starts automatically. ## Option 2: Self-host on your own VPS For full control over your deployment, run uproot behind [nginx](https://nginx.org/en/docs/beginners_guide.html), a web server that forwards requests to uproot as a *reverse proxy*. You manage the server, certificates, and software yourself. This is the most sovereign option: participants connect directly to your VPS, and you choose who provides the infrastructure. **We strongly recommend that you use a VPS with Debian 13+.** (While uproot itself works flawlessly on Ubuntu, using Ubuntu is in general considered bad practice. uproot also works on OpenBSD.) !!! tip "New to VPS deployment?" If you are setting up a server from scratch, follow the [complete VPS setup guide](https://uproot.science/running/vps-setup.md). It covers everything from getting a VPS to a working HTTPS setup, step by step. !!! warning "HTTPS required" uproot requires HTTPS in production. Many browser features (like the secure cookies needed for accessing the admin area) only work over HTTPS. Use [Let’s Encrypt](https://letsencrypt.org/) with [Certbot](https://certbot.eff.org/instructions) to get free TLS certificates—the credentials your web server uses to provide HTTPS. ### Running uproot The simplest approach is a tmux session that persists after you disconnect: ```bash tmux new -s uproot uproot run # or: uv run uproot run ``` Detach with ++ctrl+b++ then ++d++. Reattach later with `tmux attach -t uproot`. For a more robust setup that survives reboots automatically, the [VPS setup guide](https://uproot.science/running/vps-setup.md#start-uproot-on-boot) shows how to create a systemd user service instead. uproot listens on port 8000 by default. Use `--port` to change it if needed. ### nginx configuration Configure nginx as a reverse proxy. [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) keep a connection open between the browser and server; the upgrade headers below are required for uproot’s [real-time features](https://uproot.science/multiplayer/real-time.md). The following example config (to be added within an existing `http` block) is battle-tested and has been proven to work reliably: ```nginx map $http_upgrade $connection_upgrade { default upgrade; "" close; } server { server_name example.com; # Adjust this listen 443 ssl; listen 443 quic; listen [::]:443 ssl; listen [::]:443 quic; http2 on; add_header Alt-Svc 'h3=":443"; ma=86400'; ssl_certificate PATH_TO_fullchain.pem; # Adjust this ssl_certificate_key PATH_TO_privkey.pem; # Adjust this location / { proxy_pass http://127.0.0.1:8000; # Maybe adjust this proxy_read_timeout 600s; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto https; proxy_set_header Front-End-Https on; proxy_set_header X-Forwarded-Protocol https; proxy_set_header X-Forwarded-Ssl on; proxy_set_header X-Url-Scheme https; proxy_buffering off; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; # Optional but recommended: do not log participant WebSockets (avoids log spam) location /ws/ { proxy_pass http://127.0.0.1:8000; # Maybe adjust this access_log off; } } } ``` ### Hosting in a subdirectory If you want to serve uproot at a path like `https://example.com/my-study/` instead of the root, set the `UPROOT_SUBDIRECTORY` environment variable to your chosen path: ```bash export UPROOT_SUBDIRECTORY=my-study # use whatever path you want uproot run ``` Leading and trailing slashes are stripped automatically, so `my-study`, `/my-study`, and `/my-study/` are all equivalent. When set, uproot prefixes all routes with the subdirectory. Hence, participant pages, the admin interface, static files, and WebSocket connections all work without any further changes to your code or templates. Then adjust your nginx config to match. Here is a complete example; the only difference from a root deployment is the `location` path: ```nginx location /my-study/ { proxy_pass http://127.0.0.1:8000; proxy_read_timeout 600s; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto https; proxy_set_header Front-End-Https on; proxy_set_header X-Forwarded-Protocol https; proxy_set_header X-Forwarded-Ssl on; proxy_set_header X-Url-Scheme https; proxy_buffering off; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; # Optional but recommended: do not log participant WebSockets (avoids log spam) location /my-study/ws/ { proxy_pass http://127.0.0.1:8000; access_log off; } } ``` The admin interface will be at `https://example.com/my-study/admin/`. !!! tip "Persistent configuration" If you run uproot via a systemd service, set the variable in an environment file or in the service unit’s `Environment=` directive so it persists across restarts. ## Option 3: Use a hosting service These services run uproot on infrastructure they manage. Choose [Fly.io](#flyio-with-sqlite) or [Render](#render-with-sqlite) to keep the default SQLite database, or [Heroku](#heroku) with PostgreSQL. Follow the storage instructions for your chosen service so that saved experiment data survives restarts. ### Fly.io with SQLite [Fly.io](https://fly.io/) supports long-running WebSocket connections and persistent volumes, so you can run uproot with its default SQLite database. Fly charges for the Machines, volumes, and network traffic that you use; check its [current pricing](https://fly.io/docs/about/pricing/) before you deploy. !!! tip "Why Fly.io?" - Full support for WebSocket connections and real-time features - Works with uproot’s default SQLite database on a persistent volume - Regional deployment for lower latency - Native support for persistent volumes #### Prerequisites 1. Create a [Fly.io account](https://fly.io/app/sign-up) 2. Install the [Fly CLI](https://fly.io/docs/flyctl/install/): === "macOS / Linux" ```bash curl -L https://fly.io/install.sh | sh ``` === "Windows (PowerShell)" ```powershell powershell -ExecutionPolicy ByPass -c "iwr https://fly.io/install.ps1 -useb | iex" ``` 3. Log in to Fly: ```bash fly auth login ``` #### Deploy your experiment Navigate to your uproot project directory and run: ```bash fly launch --no-deploy ``` The `--no-deploy` option is important: it lets you attach persistent storage before uproot starts for the first time. Fly will detect your Python application and guide you through the setup. When prompted: - Choose an app name or let Fly generate one - Choose a region close to your participants - Do not add PostgreSQL or Redis if Fly offers them This creates a `fly.toml` configuration file. Edit it to ensure the correct settings: ```toml app = "your-app-name" primary_region = "iad" # or your chosen region [build] builder = "paketobuildpacks/builder-jammy-base" [env] PORT = "8080" UPROOT_SQLITE3 = "/data/uproot.sqlite3" UPROOT_ORIGIN = "https://your-app-name.fly.dev" [http_service] internal_port = 8080 force_https = true auto_stop_machines = "off" # Keep WebSocket connections alive auto_start_machines = true min_machines_running = 1 [[vm]] memory = "512mb" cpu_kind = "shared" cpus = 1 ``` Replace `your-app-name` and `iad` with the app name and region selected by `fly launch`. If you later add a custom domain, update `UPROOT_ORIGIN` to that domain. #### Adding persistent storage for SQLite Create a persistent volume to ensure your SQLite database survives app restarts: ```bash fly volumes create uproot_data --region iad --size 1 ``` Update your `fly.toml` to mount the volume: ```toml [mounts] source = "uproot_data" destination = "/data" ``` The `UPROOT_SQLITE3` setting above points uproot at the mounted volume. !!! warning "Use one Machine" A Fly volume is attached to one Machine and is not automatically replicated. Keep this SQLite deployment at one Machine; do not clone the Machine or scale it horizontally. #### Set the admin password New uproot projects use `upd.auto_login()` in `main.py`. Set the production password as a Fly secret so that it is not committed to Git: ```bash fly secrets set UPROOT_ADMIN_PASSWORD='choose-a-long-random-password' ``` If your project does not already contain this line, add it to `main.py`: ```python upd.ADMINS["admin"] = upd.auto_login() ``` #### Deploy Deploy your application: ```bash fly deploy ``` After deployment completes, Fly will show your app’s URL. Open it in your browser: ```bash fly open ``` #### Monitoring and logs View your app’s logs: ```bash fly logs ``` Check app status: ```bash fly status ``` Access the admin interface at `https://your-app-name.fly.dev/admin/`. ### Render with SQLite [Render](https://render.com/) supports WebSockets without a fixed connection timeout and can attach a persistent disk to a paid web service. Do not use a free web service for a real experiment: free services cannot attach a disk, and their local SQLite files are [lost when the service restarts, redeploys, or spins down](https://render.com/docs/free#local-files-lost-on-redeploy). #### Quick start 1. Sign up at [render.com](https://render.com/) and select **New > Web Service**. 2. Connect the Git repository that contains your uproot project and choose the **Python 3** runtime. 3. Set the build command to `pip install -r requirements.txt`. 4. Set the start command to `uproot run -h 0.0.0.0 -p $PORT`. 5. Choose a paid instance type. Under **Advanced**, add a persistent disk with the mount path `/var/data`. 6. Add the following environment variables, replacing the example service name and password: ```text UPROOT_SQLITE3=/var/data/uproot.sqlite3 UPROOT_ORIGIN=https://your-service-name.onrender.com UPROOT_ADMIN_PASSWORD=choose-a-long-random-password ``` 7. Create the web service. When the first deploy finishes, open `https://your-service-name.onrender.com/admin/`. The password variable assumes that `main.py` contains `upd.ADMINS["admin"] = upd.auto_login()`, as current uproot projects do. Add that line if you have an older project. Render’s Python runtime uses the project’s `.python-version` file, so the file generated by uproot selects a compatible Python version. If you add a custom domain, update `UPROOT_ORIGIN` to its full `https://` URL. !!! warning "Persistent-disk limitations" A Render persistent disk is available to only one service instance and [disables zero-downtime deploys](https://render.com/docs/disks#disk-limitations-and-considerations). This matches uproot’s single-process live state, but it means each deploy briefly stops the experiment. Keep one instance and do not deploy while participants are active. Render can also replace an instance during platform maintenance, which closes its [WebSocket connections](https://render.com/docs/websocket#faq). ### Heroku Heroku can run uproot with PostgreSQL. A Heroku dyno’s local disk is temporary, so the default SQLite database is not suitable for production there. !!! note "WebSocket timeout" Heroku supports WebSockets and applies a rolling [55-second idle timeout](https://devcenter.heroku.com/articles/websockets). uproot sends a heartbeat every 9 seconds, so a participant reading or waiting does not leave the connection idle long enough to hit that limit. !!! warning "Dyno restarts" Heroku [restarts dynos at least daily](https://devcenter.heroku.com/articles/dyno-restarts), as well as after deploys and configuration changes. PostgreSQL keeps the saved data, but a restart interrupts active connections and in-process background tasks. Restart or deploy shortly before a scheduled experiment, and do not change the app while participants are active. #### Prerequisites 1. Create a [Heroku account](https://signup.heroku.com/) 2. Install the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) 3. Log in to Heroku: ```bash heroku login ``` #### Deploy your experiment First, add PostgreSQL support to the project’s main dependencies: ```bash uv add 'uproot-science[pg]<1' ``` This updates `pyproject.toml` and `uv.lock`. Current uproot projects also contain a `requirements.txt`, but Heroku’s Python buildpack [requires exactly one package-manager file](https://github.com/heroku/heroku-buildpack-python/blob/main/lib/package_manager.sh). Remove `requirements.txt` from Git so that Heroku uses the lock file: ```bash git rm requirements.txt git add pyproject.toml uv.lock git commit -m "Configure Heroku deployment" ``` The generated `Procfile` already binds uproot to Heroku’s `$PORT`. Make sure `main.py` contains `upd.ADMINS["admin"] = upd.auto_login()`. Then create the app, enable runtime metadata so uproot can discover its public URL, add PostgreSQL, and set the admin password: ```bash # Create a new Heroku app heroku create my-experiment-name # Enable runtime metadata heroku labs:enable runtime-dyno-metadata # Provision PostgreSQL heroku addons:create heroku-postgresql:essential-0 heroku pg:wait # Store the admin password outside the source code heroku config:set UPROOT_ADMIN_PASSWORD='choose-a-long-random-password' # Deploy git push heroku main # Keep uproot on exactly one web dyno heroku ps:scale web=1:basic # Open the admin interface heroku open /admin/ ``` If your local branch is not named `main`, deploy it with `git push heroku HEAD:main` instead. The PostgreSQL add-on sets `DATABASE_URL`; uproot detects it automatically. If you add a custom domain, set `UPROOT_ORIGIN` to its full `https://` URL with `heroku config:set`. !!! warning "Do not scale horizontally" uproot’s live connection queues and background tasks belong to one server process. Keep exactly one web dyno; adding more web dynos would split participants across processes that do not share that live state. --- Source: https://uproot.science/running/vps-setup.md # VPS setup guide Step-by-step instructions for deploying uproot on a fresh virtual private server (VPS). This guide assumes no prior server administration experience and produces a minimal, production-ready setup. ## 1. Get a VPS Rent a virtual private server from any major provider. [Hetzner](https://www.hetzner.com/), [DigitalOcean](https://www.digitalocean.com/), and [AWS Lightsail](https://aws.amazon.com/lightsail/) are all good options. uproot is lightweight; the smallest available tier (1 vCPU, 512 MB to 1 GB RAM) is sufficient for most experiments. Choose **Debian** (latest stable) as the operating system. We recommend Debian for reasons we need not elaborate here. ## 2. Secure SSH access ### Generate an SSH key (on your local machine) If you do not yet have an SSH key, create one: ```console you@local:~$ ssh-keygen -t ed25519 ``` Accept the default file location. Your public key is at `~/.ssh/id_ed25519.pub`. Most VPS providers let you paste your public key during server creation. If you did that, you can SSH in as root immediately: ```console you@local:~$ ssh root@YOUR_SERVER_IP ``` If you did not add a key during creation, log in with the password the provider gave you, then install your key: ```console you@local:~$ ssh-copy-id -i ~/.ssh/id_ed25519.pub root@YOUR_SERVER_IP ``` ### Create a non-root user Do not run experiments as root. Create a normal user and give it sudo access: ```console root@server:~# adduser uproot root@server:~# usermod -aG sudo uproot ``` `adduser` asks you to set a password (you will need it for `sudo` later) and some optional fields you can skip by pressing Enter. ### Set up SSH keys for both users Your root account already has your SSH key. Copy it to the new user so you can log in as either: ```console root@server:~# mkdir -p /home/uproot/.ssh root@server:~# cp /root/.ssh/authorized_keys /home/uproot/.ssh/authorized_keys root@server:~# chown -R uproot:uproot /home/uproot/.ssh root@server:~# chmod 700 /home/uproot/.ssh root@server:~# chmod 600 /home/uproot/.ssh/authorized_keys ``` ### Disable password login Root login is still allowed, but only with SSH keys. This is convenient for emergency administration while still preventing password-based logins. ```console root@server:~# nano /etc/ssh/sshd_config.d/99-keys-only.conf ``` !!! tip In `nano`, save with ++ctrl+s++ and exit with ++ctrl+x++. Paste the following: ```ini PasswordAuthentication no KbdInteractiveAuthentication no PermitRootLogin prohibit-password ``` Then test and apply: ```console root@server:~# sshd -t root@server:~# systemctl restart ssh ``` !!! warning Before closing this session, verify in a **separate terminal** that your key works for **both** users: ```console you@local:~$ ssh root@YOUR_SERVER_IP you@local:~$ ssh uproot@YOUR_SERVER_IP ``` Both must succeed. If either fails, fix it before closing your root session. Otherwise you may lock yourself out. From now on, use `root@server` for system administration and `uproot@server` for managing your experiment. ## 3. Install system packages Still as root: ```console root@server:~# apt update && apt install -y git python3 python-is-python3 python3-pip python3-venv nginx certbot python3-certbot-nginx tmux unattended-upgrades dnsutils root@server:~# dpkg-reconfigure -plow unattended-upgrades ``` Select “Yes” when prompted to enable automatic security updates. This ensures critical patches are installed without your intervention. ## 4. Set up your project From here on, work as the `uproot` user: ```console you@local:~$ ssh uproot@YOUR_SERVER_IP ``` ### Upload your project In a separate terminal on your local machine, copy your uproot project to the server: ```console you@local:~$ rsync --delete -Pa my_project uproot@YOUR_SERVER_IP: ``` ### Before going to production Edit `main.py` on the server to set a real admin password: ```python upd.ADMINS["admin"] = "your-secure-password" ``` ### Create a Python environment ```console uproot@server:~$ python3 -m venv ~/env uproot@server:~$ source ~/env/bin/activate (env) uproot@server:~$ cd ~/my_project (env) uproot@server:~/my_project$ pip install -Ue . ``` Verify it works: ```console (env) uproot@server:~/my_project$ uproot run -h 127.0.0.1 -p 8000 ``` Stop it with ++ctrl+c++ once you see the startup output. The remaining steps do not require the virtual environment. ### Create a run script ```console uproot@server:~$ nano ~/run.sh ``` Paste the following: ```bash #!/bin/bash set -e cd ~/my_project source ~/env/bin/activate pip install -Ue . export UPROOT_ORIGIN=https://example.com exec uproot run -h 127.0.0.1 -p 8000 ``` Save, exit, then make it executable: ```console uproot@server:~$ chmod +x ~/run.sh ``` Replace `example.com` with your actual hostname (see [step 5](#choose-a-hostname)). The script reinstalls your project on every start (picking up any dependency changes) and starts uproot on a local-only port. nginx will handle the public-facing side. ### Start uproot on boot There are two ways to keep uproot running: a systemd user service (automatic, survives reboots) or tmux (manual, simpler to understand). We recommend systemd, but tmux is a perfectly reasonable alternative. See the [deployment page](https://uproot.science/running/deployment.md#running-uproot) for the tmux approach. #### systemd (recommended) Create a user-level systemd service so uproot starts automatically when the server boots. First enable lingering, which allows the user’s systemd services to run even when the user is not logged in: ```console uproot@server:~$ sudo loginctl enable-linger uproot ``` Then create the service: ```console uproot@server:~$ mkdir -p ~/.config/systemd/user uproot@server:~$ nano ~/.config/systemd/user/uproot.service ``` Paste the following: ```ini [Unit] Description=uproot experiment server After=network.target [Service] Type=exec ExecStart=%h/run.sh Restart=on-failure RestartSec=5 [Install] WantedBy=default.target ``` Enable and start it: ```console uproot@server:~$ systemctl --user daemon-reload uproot@server:~$ systemctl --user enable uproot uproot@server:~$ systemctl --user start uproot ``` Useful commands: | Command | What it does | |---------|-------------| | `systemctl --user status uproot` | Check if uproot is running | | `systemctl --user restart uproot` | Restart after updating your project | | `journalctl --user -u uproot -f` | Follow the live log output | | `systemctl --user stop uproot` | Stop the server | ## 5. nginx and HTTPS ### Choose a hostname You need a domain name for HTTPS. A custom domain is not required; there are easier options: - **Provider-assigned hostname:** Some VPS providers let you assign a hostname through their control panel. If your provider offers this and the hostname already resolves to your server’s IP, you can use it directly and skip the DNS step below. - **University subdomain:** Many universities allow researchers to create subdomains (such as `experiment.econ.uni-example.de`). Ask your IT department. This is often the easiest and most professional-looking option. - **Your own domain:** Register one from any registrar if you prefer full control. If you are using a university subdomain or your own domain, create a **DNS A record** pointing it to your server’s IP address. Wait for it to propagate (usually a few minutes, sometimes up to an hour). You can verify with: ```console uproot@server:~$ dig +short example.com ``` This should return your server’s IP. ### Get a TLS certificate Stop nginx temporarily so certbot can use port 80: ```console uproot@server:~$ sudo systemctl stop nginx uproot@server:~$ sudo certbot certonly --standalone -d example.com ``` Follow the prompts. Certbot stores the certificate at `/etc/letsencrypt/live/example.com/`. ### Set up automatic renewal Certbot installs a systemd timer that attempts renewal twice daily. Since we used standalone mode, nginx needs to briefly stop during renewal. Create hooks for this: ```console uproot@server:~$ sudo mkdir -p /etc/letsencrypt/renewal-hooks/pre /etc/letsencrypt/renewal-hooks/post uproot@server:~$ sudo nano /etc/letsencrypt/renewal-hooks/pre/stop-nginx ``` Paste the following: ```bash #!/bin/bash systemctl stop nginx ``` Then create the post-renewal hook: ```console uproot@server:~$ sudo nano /etc/letsencrypt/renewal-hooks/post/start-nginx ``` Paste the following: ```bash #!/bin/bash systemctl start nginx ``` Make both hooks executable: ```console uproot@server:~$ sudo chmod +x /etc/letsencrypt/renewal-hooks/pre/stop-nginx /etc/letsencrypt/renewal-hooks/post/start-nginx ``` Certificates are valid for 90 days. Renewal is attempted automatically roughly every three weeks once a certificate is past the halfway point. Verify the setup with: ```console uproot@server:~$ sudo certbot renew --dry-run ``` ### Configure nginx Remove the default site and create the uproot configuration: ```console uproot@server:~$ sudo rm -f /etc/nginx/sites-enabled/default uproot@server:~$ sudo nano /etc/nginx/sites-available/uproot ``` Paste the following. Replace every occurrence of `example.com` with your hostname: ```nginx map $http_upgrade $connection_upgrade { default upgrade; "" close; } server { listen 80; listen [::]:80; server_name example.com; return 301 https://$host$request_uri; } server { server_name example.com; listen 443 ssl; listen 443 quic; listen [::]:443 ssl; listen [::]:443 quic; http2 on; add_header Alt-Svc 'h3=":443"; ma=86400'; ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; location / { proxy_pass http://127.0.0.1:8000; proxy_read_timeout 600s; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto https; proxy_set_header Front-End-Https on; proxy_set_header X-Forwarded-Protocol https; proxy_set_header X-Forwarded-Ssl on; proxy_set_header X-Url-Scheme https; proxy_buffering off; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; # Optional but recommended: do not log participant WebSockets (avoids log spam) location /ws/ { proxy_pass http://127.0.0.1:8000; access_log off; } } } ``` Enable the site and start nginx: ```console uproot@server:~$ sudo ln -sf /etc/nginx/sites-available/uproot /etc/nginx/sites-enabled/uproot uproot@server:~$ sudo nginx -t && sudo systemctl start nginx ``` `nginx -t` tests the configuration. If it reports errors, double-check that you replaced all occurrences of `example.com` and that the certificate paths exist. ## 6. Go live If uproot is not already running via the systemd service: ```console uproot@server:~$ systemctl --user start uproot ``` Your experiment is now live at `https://example.com/admin/`. ### Updating your experiment Upload the new version from your local machine, then restart: ```console you@local:~$ rsync --delete -Pa my_project uproot@YOUR_SERVER_IP: ``` ```console uproot@server:~$ systemctl --user restart uproot ``` The run script automatically reinstalls your project and picks up any changes. ### Maintenance Restart your server regularly (e.g., every few weeks, and always between experiment sessions) to apply kernel updates installed by `unattended-upgrades`. Many security patches only take full effect after a reboot: ```console uproot@server:~$ sudo reboot ``` uproot starts back up automatically thanks to the systemd service. After reconnecting, verify: ```console uproot@server:~$ systemctl --user status uproot ``` --- Source: https://uproot.science/reference/fields.md # Form fields All fields accept keyword-only arguments. See [Collecting data with forms](https://uproot.science/building/forms.md) for usage patterns. ## Common parameters These parameters are available on most fields: | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `label` | `str` | `""` | Question text shown to the participant | | `optional` | `bool` | `False` | Allow empty responses | | `description` | `str` | `""` | Help text below the field | | `default` | any | `None` | Pre-filled value | | `render_kw` | `dict` | `None` | HTML attributes for the input element | | `widget` | any | `None` | Custom WTForms widget | | `class_wrapper`{ .text-nowrap } | `str` | `None` | CSS class for the wrapper div | For several Likert items sharing one scale, use the `likert_matrix()` or `likert_grid()` template macros. See [Collecting data with forms](https://uproot.science/building/forms.md#scales-and-sliders). ## `BooleanField` A single checkbox. ```python consent=BooleanField(label="I agree to participate") ``` | Parameter | Type | Default | |-----------|------|---------| | `label` | `str` | `""` | | `render_kw` | `dict` | `None` | | `description` | `str` | `""` | | `widget` | any | `None` | | `default` | any | `None` | | `class_wrapper`{ .text-nowrap } | `str` | `None` | | `validators` | list | — | ## `BoundedChoiceField` Multi-select checkboxes with min/max selection limits. ```python topics=BoundedChoiceField( label="Select your preferred topics", choices=["Economics", "Psychology", "Sociology"], min=1, max=3, ) ``` | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `choices` | list or dict | — | Available options | | `min` | `int` | `0` | Minimum number of selections | | `max` | `int` | `None` | Maximum selections (`None` = unlimited) | | `layout` | `str` | `"vertical"` | `"vertical"` or `"horizontal"` | | `label` | `str` | `""` | | | `description` | `str` | `""` | | | `render_kw` | `dict` | `None` | | | `widget` | any | `None` | | | `default` | any | `None` | | | `class_wrapper`{ .text-nowrap } | `str` | `None` | | Returns a list of selected values. [See the bounded_choice example](https://github.com/mrpg/uproot-examples/tree/main/bounded_choice) ## `DateField` A date picker. ```python birthdate=DateField(label="Date of birth") ``` | Parameter | Type | Default | |-----------|------|---------| | `label` | `str` | `""` | | `optional` | `bool` | `False` | | `render_kw` | `dict` | `None` | | `description` | `str` | `""` | | `widget` | any | `None` | | `default` | any | `None` | | `class_wrapper`{ .text-nowrap } | `str` | `None` | ## `DecimalField` Decimal number input with optional addons and min/max bounds. ```python amount=DecimalField( label="Amount to contribute", min=0.0, max=100.0, step=0.01, addon_start="$", ) ``` | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `min` | number | — | Minimum value | | `max` | number | — | Maximum value | | `step` | number | — | Step increment | | `addon_start` | `str` | — | Text before the input (e.g., `"$"`) | | `addon_end` | `str` | — | Text after the input (e.g., `"EUR"`) | | `class_addon_start`{ .text-nowrap } | `str` | `""` | CSS class for start addon | | `class_addon_end` | `str` | `""` | CSS class for end addon | | `label` | `str` | `""` | | | `optional` | `bool` | `False` | | | `render_kw` | `dict` | `None` | | | `description` | `str` | `""` | | | `widget` | any | `None` | | | `default` | any | `None` | | | `class_wrapper` | `str` | `None` | | ## `FloatField` Like `DecimalField`, but stores a Python `float`. Prefer `DecimalField` for money. ```python reaction_time=FloatField(label="Reaction time (seconds)", min=0.0, step=0.001) ``` It accepts the same `min`, `max`, `step`, addon, label, optional, rendering, and wrapper parameters as `DecimalField`. ## `DecimalRangeField` A slider input. ```python confidence=DecimalRangeField( label="How confident are you?", min=0, max=100, step=1, label_min="Not at all", label_max="Completely", ) ``` | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `min` | number | — | Minimum value | | `max` | number | — | Maximum value | | `step` | number | `1.0` | Step increment | | `label_min` | `str` | `None` | Label below left end (defaults to `str(min)`) | | `label_max` | `str` | `None` | Label below right end (defaults to `str(max)`) | | `breakpoint` | `int` | `992` | Viewport width in pixels at or above which endpoint labels no longer wrap | | `label_max_min_class_suffix`{ .text-nowrap } | `str` | `"-custom"` | CSS class suffix for endpoint labels | | `hide_popover` | `bool` | `False` | Hide the current value popover | | `anchoring` | `bool` | `True` | Show initial slider position | | `label` | `str` | `""` | | | `optional` | `bool` | `False` | | | `render_kw` | `dict` | `None` | | | `description` | `str` | `""` | | | `widget` | any | `None` | | | `default` | any | `None` | | | `class_wrapper` | `str` | `None` | | [See the input_elements example](https://github.com/mrpg/uproot-examples/tree/main/input_elements) ## `FloatRangeField` Like `DecimalRangeField`, but stores a Python `float`. It accepts the same slider parameters (`min`, `max`, `step`, `label_min`, `label_max`, `breakpoint`, `hide_popover`, `anchoring`, and the rest). ## `EmailField` HTML email input. It checks required/optional status like other fields; add a page `validate` method if you need stricter server-side email validation. ```python email=EmailField(label="Your email address") ``` | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `label_floating`{ .text-nowrap } | `str` | `None` | Floating label inside the input | | `label` | `str` | `""` | | | `optional` | `bool` | `False` | | | `render_kw` | `dict` | `None` | | | `description` | `str` | `""` | | | `widget` | any | `None` | | | `default` | any | `None` | | | `class_wrapper` | `str` | `None` | | ## `FileField` File upload. Always treated as a stealth field. Process in `handle_stealth_fields`. ```python document=FileField(label="Upload your document") ``` See [File uploads](https://uproot.science/advanced/uploads.md) for details. | Parameter | Type | Default | |-----------|------|---------| | `label` | `str` | `""` | | `optional` | `bool` | `False` | | `render_kw` | `dict` | `None` | | `description` | `str` | `""` | | `widget` | any | `None` | | `default` | any | `None` | | `class_wrapper`{ .text-nowrap } | `str` | `None` | ## `IBANField` IBAN input with format validation. Install the optional `iban` extra first with `uv add 'uproot-science[iban]<1'`; it provides the `schwifty` library used for validation. ```python iban=IBANField(label="Your IBAN") ``` | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `addon_start` | `str` | — | Text before the input | | `addon_end` | `str` | — | Text after the input | | `class_addon_start`{ .text-nowrap } | `str` | `""` | CSS class for start addon | | `class_addon_end` | `str` | `""` | CSS class for end addon | | `label_floating` | `str` | `None` | Floating label inside the input | | `label` | `str` | `""` | | | `optional` | `bool` | `False` | | | `render_kw` | `dict` | `None` | | | `description` | `str` | `""` | | | `widget` | any | `None` | | | `default` | any | `None` | | | `class_wrapper` | `str` | `None` | | [See the payment_data example](https://github.com/mrpg/uproot-examples/tree/main/payment_data) ## `IntegerField` Whole number input with optional addons and min/max bounds. ```python age=IntegerField(label="How old are you?", min=18, max=100) ``` | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `min` | `int` | — | Minimum value | | `max` | `int` | — | Maximum value | | `addon_start` | `str` | — | Text before the input | | `addon_end` | `str` | — | Text after the input | | `class_addon_start`{ .text-nowrap } | `str` | `""` | CSS class for start addon | | `class_addon_end` | `str` | `""` | CSS class for end addon | | `label` | `str` | `""` | | | `optional` | `bool` | `False` | | | `render_kw` | `dict` | `None` | | | `description` | `str` | `""` | | | `widget` | any | `None` | | | `default` | any | `None` | | | `class_wrapper` | `str` | `None` | | ## `BICField` BIC/SWIFT code input with format validation (requires the optional `iban` extra described under [IBANField](#ibanfield)). ```python bic=BICField(label="Your bank’s BIC") ``` It accepts the same addon, label, optional, rendering, and wrapper parameters as `IBANField`. See [the payment data example](https://github.com/mrpg/uproot-examples/tree/main/payment_data). ## `LikertField` Rating scale rendered as radio buttons with labeled endpoints. ```python satisfaction=LikertField( label="How satisfied are you?", label_min="Very unsatisfied", label_max="Very satisfied", min=1, max=7, ) ``` | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `min` | `int` | `1` | Lowest value | | `max` | `int` | `7` | Highest value | | `label_min` | `str` | `""` | Label below the lowest value | | `label_max` | `str` | `""` | Label below the highest value | | `breakpoint` | `int` | `992` | Viewport width in pixels at or above which the scale stays horizontal | | `choices` | list or dict | auto | Override the auto-generated integer choices | | `label` | `str` | `""` | | | `optional` | `bool` | `False` | | | `render_kw` | `dict` | `None` | | | `description` | `str` | `""` | | | `widget` | any | `None` | | | `default` | any | `None` | | | `class_wrapper`{ .text-nowrap } | `str` | `None` | | Auto-generates integer choices from `min` to `max`. ## `LikertFieldClassic` The same scale as `LikertField`, always rendered as a table. Use this when you do not want the responsive layout. It accepts `min`, `max`, `label_min`, `label_max`, `choices`, and the usual label/optional/rendering parameters, but not `breakpoint`. ## `RadioField` Choose one option with radio buttons. ```python choice=RadioField( label="Do you agree?", choices=[(True, "Yes"), (False, "No")], ) ``` | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `choices` | list, dict, or `None` | `None` | Options (defaults to `[True, False]` if `None`) | | `layout` | `str` | `"vertical"` | `"vertical"` or `"horizontal"` | | `label` | `str` | `""` | | | `optional` | `bool` | `False` | | | `render_kw` | `dict` | `None` | | | `description` | `str` | `""` | | | `widget` | any | `None` | | | `default` | any | `None` | | | `class_wrapper`{ .text-nowrap } | `str` | `None` | | Choices can be: - `list[tuple[value, label]]`, for example, `[(1, "Option A"), (2, "Option B")]`; - `dict[value, label]`, for example, `{"a": "Option A", "b": "Option B"}`; - `list[value]`, for example, `[1, 2, 3]` (value and label are the same). ## `SelectField` Dropdown selection. ```python country=SelectField( label="Country", choices=[("us", "United States"), ("de", "Germany")], ) ``` | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `choices` | list or dict | — | Options (required) | | `label` | `str` | `""` | | | `optional` | `bool` | `False` | | | `render_kw` | `dict` | `None` | | | `description` | `str` | `""` | | | `widget` | any | `None` | | | `default` | any | `None` | | | `class_wrapper`{ .text-nowrap } | `str` | `None` | | Accepts the same choice formats as `RadioField`. The dropdown starts with an empty option (“—”), which is selected until the participant picks a choice. For required fields, submitting the empty option fails validation. For optional fields, it saves `None`. If your choices already include an empty value (`""`), no extra option is added, so you can label it yourself: ```python country=SelectField( label="Country", choices=[("", "Please choose"), ("us", "United States"), ("de", "Germany")], ) ``` With your own empty choice, an optional field saves `""` instead of `None`. ## `StringField` Single-line text input. ```python participant_name=StringField(label="Your name") ``` | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `addon_start` | `str` | — | Text before the input | | `addon_end` | `str` | — | Text after the input | | `class_addon_start`{ .text-nowrap } | `str` | `""` | CSS class for start addon | | `class_addon_end` | `str` | `""` | CSS class for end addon | | `label_floating` | `str` | `None` | Floating label inside the input | | `label` | `str` | `""` | | | `optional` | `bool` | `False` | | | `render_kw` | `dict` | `None` | | | `description` | `str` | `""` | | | `widget` | any | `None` | | | `default` | any | `None` | | | `class_wrapper` | `str` | `None` | | ## `TextAreaField` Multi-line text input. ```python comments=TextAreaField(label="Additional comments", optional=True) ``` | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `addon_start` | `str` | — | Text before the input | | `addon_end` | `str` | — | Text after the input | | `class_addon_start`{ .text-nowrap } | `str` | `""` | CSS class for start addon | | `class_addon_end` | `str` | `""` | CSS class for end addon | | `label_floating` | `str` | `None` | Floating label inside the input | | `label` | `str` | `""` | | | `optional` | `bool` | `False` | | | `render_kw` | `dict` | `None` | | | `description` | `str` | `""` | | | `widget` | any | `None` | | | `default` | any | `None` | | | `class_wrapper` | `str` | `None` | | [See all field types in the input_elements example](https://github.com/mrpg/uproot-examples/tree/main/input_elements) --- Source: https://uproot.science/reference/page-methods.md # Page methods Page methods are `@classmethod`s that receive `page` (the page class) and usually `player` (the current participant) as arguments. Standard page hooks can be sync or async; wait-page callbacks such as `after_grouping` and `all_here` are sync-only. ## Lifecycle overview For a forward visit to a page, the lifecycle is: 1. **`show`:** Decide whether the page is displayed. 2. **`early`:** Run before rendering. 3. **`before_always_once`:** Run once when this page position is reached. 4. **`before_once`:** Run once per player, on first visit only. 5. **`fields`:** Determine form fields. 6. **`templatevars` and `jsvars`:** Prepare template and JS data. 7. *(The page is rendered and displayed.)* 8. *(The participant submits.)* 9. **`validate`:** Check submitted data. 10. **`before_form_save`:** Run before ordinary form fields are saved. 11. **`stealth_fields` and `handle_stealth_fields`:** Handle manual fields. 12. **`may_proceed`:** Gate before advancing. 13. **`after_once`:** Run once per player, on first successful submission only. 14. **`after_always_once`:** Run once after this page position is submitted. The `timeout` method configures the deadline while the page is rendered. The browser submits when the deadline is reached. If the server receives a request after the deadline, `timeout_reached` handles that request before normal form processing, `may_proceed` is skipped, and the page advances. Valid form data is saved; invalid data is discarded without an error message. uproot counts a request up to `upd.TIMEOUT_TOLERANCE` seconds (default: 1) before the deadline as timed out, too, but only if `may_proceed` allows the page to advance. See [Timeouts and `may_proceed`](https://uproot.science/advanced/timeouts.md#timeouts-and-may_proceed). A direct visit to the current page can omit `early`, because that hook runs when entering a new page position. ## `show` Decides whether the page should be displayed. Return `False` to skip the page entirely. ```python @classmethod def show(page, player): return player.role == "proposer" ``` | Parameter | Description | |-----------|-------------| | `page` | The page class | | `player` | The current player | | **Returns** | `bool`: `True` to show (default), `False` to skip | ## `early` The earliest hook in the page lifecycle. Runs before `before_always_once`. Receives the HTTP request as an additional keyword argument. ```python @classmethod def early(page, player, request): player.user_agent = request.headers.get("user-agent", "") ``` | Parameter | Description | |-----------|-------------| | `page` | The page class | | `player` | The current player | | `request` | The Starlette `Request` object | ## `before_once` Runs **once per player**, the first time they see this page. Does not run again if the player navigates back and returns. ```python @classmethod def before_once(page, player): player.start_time = time() ``` | Parameter | Description | |-----------|-------------| | `page` | The page class | | `player` | The current player | ## `before_always_once` Runs once when this page position is reached. Use this for setup that should also happen for internal or skipped pages. ```python @classmethod def before_always_once(page, player): player.visit_count = getattr(player, "visit_count", 0) + 1 ``` | Parameter | Description | |-----------|-------------| | `page` | The page class | | `player` | The current player | ## `fields` Returns the form fields for this page. Can be a dictionary (static) or a method (dynamic). ### Static fields ```python class Survey(Page): fields = dict( age=IntegerField(label="Age", min=18, max=100), ) ``` ### Dynamic fields ```python @classmethod def fields(page, player): max_offer = player.other_in_group.endowment return dict( offer=IntegerField(label="Your offer", min=0, max=max_offer), ) ``` | Parameter | Description | |-----------|-------------| | `page` | The page class | | `player` | The current player | | **Returns** | `dict` mapping field names to field instances | ## `templatevars` Returns variables available in the page template. ```python @classmethod def templatevars(page, player): return dict( partner=player.other_in_group, total=sum(p.contribution for p in player.group.players), ) ``` | Parameter | Description | |-----------|-------------| | `page` | The page class | | `player` | The current player | | **Returns** | `dict` of template variables, or `None` | `templatevars` may return `None` instead of a dict. This is treated the same as returning `{}`. ## `jsvars` Returns variables available in JavaScript as `uproot.vars`. ```python @classmethod def jsvars(page, player): return dict( initial_price=player.price, max_trades=C.MAX_TRADES, ) ``` Access in JavaScript: ```javascript const price = uproot.vars.initial_price; ``` | Parameter | Description | |-----------|-------------| | `page` | The page class | | `player` | The current player | | **Returns** | `dict` of JavaScript variables | ## `validate` Custom validation of submitted form data. Called after built-in field validation passes. ```python @classmethod def validate(page, player, data): if data["give_a"] + data["give_b"] > 100: return "Total cannot exceed 100" ``` | Parameter | Description | |-----------|-------------| | `page` | The page class | | `player` | The current player | | `data` | `dict` of submitted values | | **Returns** | Error message(s), or nothing if valid | Return types are: - `str`: single error displayed at the top of the form; - `list[str]`: multiple errors displayed at the top; - `dict[str, str | list[str]]`: per-field errors displayed next to each field. ```python @classmethod def validate(page, player, data): errors = {} if data["min_price"] > data["max_price"]: errors["min_price"] = "Must be less than max price" errors["max_price"] = "Must be greater than min price" return errors or None ``` [See the input_validation example](https://github.com/mrpg/uproot-examples/tree/main/input_validation) ## `before_form_save` Runs after built-in and custom validation passes, immediately before ordinary form fields are saved to the player. The submitted `data` mapping is read-only; use this hook for checks or side effects that need the validated values before they are persisted. ```python @classmethod def before_form_save(page, player, data): player.submitted_at = time() ``` | Parameter | Description | |-----------|-------------| | `page` | The page class | | `player` | The current player | | `data` | Read-only mapping of validated form values | ## `may_proceed` Gate that controls whether the player can advance. Return `False` to keep the player on the page. ```python @classmethod def may_proceed(page, player): from time import time return time() >= player.session.detection_period_until ``` | Parameter | Description | |-----------|-------------| | `page` | The page class | | `player` | The current player | | **Returns** | `bool`: `True` to allow proceeding (default), `False` to block | !!! note A page [timeout](#timeout) overrides `may_proceed` once the deadline has passed. See [Timeouts and `may_proceed`](https://uproot.science/advanced/timeouts.md#timeouts-and-may_proceed). ## `after_once` Runs **once per player**, after the first forward submission. Does not run on back navigation or revisits. ```python @classmethod def after_once(page, player): player.completed_task = True ``` | Parameter | Description | |-----------|-------------| | `page` | The page class | | `player` | The current player | ## `after_always_once` Runs once after this page position is submitted in the forward direction. ```python @classmethod def after_always_once(page, player): player.attempts += 1 ``` | Parameter | Description | |-----------|-------------| | `page` | The page class | | `player` | The current player | !!! note `after_once` and `after_always_once` are not available on `GroupCreatingWait` or `SynchronizingWait` pages. ## `timeout` Sets a page timeout in seconds. Can be a static value or a method. ### Static timeout ```python class TimedTask(Page): timeout = 60 ``` ### Dynamic timeout ```python @classmethod def timeout(page, player): return max(0, player.deadline - time()) ``` | Parameter | Description | |-----------|-------------| | `page` | The page class | | `player` | The current player | | **Returns** | `float` seconds until timeout, or `None` to disable | ## `timeout_reached` Called when the page timeout expires, before the page auto-advances. ```python @classmethod def timeout_reached(page, player): player.timed_out = True player.score = 0 ``` | Parameter | Description | |-----------|-------------| | `page` | The page class | | `player` | The current player | ## `stealth_fields` Specifies which fields should not be saved automatically. Can be a list or a method. ### Static stealth fields ```python class MyPage(Page): stealth_fields = ["code", "iban"] ``` ### Dynamic stealth fields ```python @classmethod def stealth_fields(page, player): return ["response"] if player.condition == "special" else [] ``` | Parameter | Description | |-----------|-------------| | `page` | The page class | | `player` | The current player | | **Returns** | `list[str]` of field names to handle manually | ## `handle_stealth_fields` Processes stealth fields. Called after validation. Return error strings to reject the submission. ```python @classmethod async def handle_stealth_fields(page, player, data): code = data["code"] if code != "secret123": return "Invalid access code" player.verified = True ``` | Parameter | Description | |-----------|-------------| | `page` | The page class | | `player` | The current player | | `data` | `dict` of stealth field values | | **Returns** | Error string or list of error strings, or nothing if valid | [See the payment_data example](https://github.com/mrpg/uproot-examples/tree/main/payment_data) · [input_validation example](https://github.com/mrpg/uproot-examples/tree/main/input_validation) ## Page class attributes | Attribute | Default | Description | |-----------|---------|-------------| | `allow_back` | `False` | Show a "Back" button | | `template` | Matching app `.html` file, then `.md` | Custom template path relative to the project root | | `keep_values`{ .text-nowrap } | `False` | Re-populate form from player data on re-render | ## Wait page methods ### `GroupCreatingWait` | Attribute/Method | Description | |------------------|-------------| | `group_size` | Required. Number of players per group | | `after_grouping(page, group)` | Called once when the group forms | ### `SynchronizingWait` | Attribute/Method | Description | |------------------|-------------| | `synchronize` | `"group"` (default) or `"session"` | | `all_here(page, group)` | Called when all group members arrive | | `all_here(page, session)` | Called when all session members arrive (if `synchronize = "session"`) | | `wait_for(page, player)` | Override to customize who to wait for | --- Source: https://uproot.science/reference/api.md # API reference This page documents the key functions and classes available when building uproot experiments. All of these are available automatically in app modules via `from uproot.smithereens import *` and `from uproot.fields import *`. ## Page types ### `Page` The standard page type. Displays a template and optionally collects form data. ```python class MyPage(Page): fields = dict(participant_name=StringField(label="Your name")) @classmethod def templatevars(page, player): return dict(greeting="Hello") ``` See [Page methods](https://uproot.science/reference/page-methods.md) for all available methods. ### `NoshowPage` A page that runs logic without displaying anything to the participant. ```python class Calculate(NoshowPage): @classmethod def after_always_once(page, player): player.payoff = player.correct * 10 ``` ### `GroupCreatingWait` A wait page that forms groups of participants. ```python class GroupPlease(GroupCreatingWait): group_size = 2 @classmethod def after_grouping(page, group): for player, role in zip(group.players, ["proposer", "responder"]): player.role = role ``` ### `SynchronizingWait` A wait page that synchronizes group or session members. ```python class Sync(SynchronizingWait): @classmethod def all_here(page, group): for player in group.players: set_payoff(player) ``` Set `synchronize = "session"` to synchronize across the entire session. ## SmoothOperators ### `RandomOrder` Shuffles pages into a random order per participant. ```python page_order = [RandomOrder(TaskA, TaskB, TaskC)] ``` ### `Bracket` Groups pages as an atomic unit within `RandomOrder` or `Between`. SmoothOperators take only pages and other SmoothOperators, so use `Bracket` instead of a list. ```python page_order = [RandomOrder(Bracket(Intro1, Task1), Bracket(Intro2, Task2))] ``` ### `Rounds` Repeats pages a fixed number of times. Sets `player.round` (1-indexed), `player.block`, and `player.round_nested`. ```python page_order = [Rounds(Decision, Feedback, n=5)] ``` | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `n` | `int` | — | Number of rounds (0 or more) | | `block` | `str` or `None` | `None` | [Block](https://uproot.science/building/operators.md#blocks) name (a valid Python identifier); required if an app can run several loops | ### `Repeat` Repeats pages indefinitely until `player.add_round = False`. Sets the same fields as `Rounds`. ```python page_order = [Repeat(Trial, Check), Done] ``` | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `block` | `str` or `None` | `None` | [Block](https://uproot.science/building/operators.md#blocks) name (a valid Python identifier); required if an app can run several loops | ### `Between` Randomly selects one option per participant. Appends the pages of the selected option to `player.between_showed`, one list per `Between` (see [Tracking which condition was shown](https://uproot.science/building/operators.md#tracking-which-condition-was-shown)). ```python page_order = [Between(Treatment, Control)] ``` ## `PlayerContext` Base class for reusable computed properties. During page execution, properties on the current app’s `Context` class are available in Python and templates as `player.context.*`. ```python class Context(PlayerContext): @property def earnings(self): return self.player.payoff * C.EXCHANGE_RATE ``` | Access | How the class is selected | Use it when | |--------|---------------------------|-------------| | `player.context` | uproot reads `player.app` and uses that app’s `Context` class | A page method or template is running inside the app | | `Context(player)`{ .text-nowrap } | Python resolves the `Context` name directly in the app module | Code is outside page execution, such as a callable `page_order(player=)` or `digest(session)` | `player.context` is `None` when the participant has no active app or the active app defines no `Context` class. See [The PlayerContext class](https://uproot.science/building/pages.md#the-playercontext-class) for the lifecycle details and examples. ## Real-time functions ### `notify` Send data from one player to one or more recipients. ```python notify(sender, recipients, data, event="EventName", where=...) ``` | Parameter | Description | |-----------|-------------| | `sender` | The sending player (determines page context) | | `recipients` | Player, `StorageBunch`, or list of players | | `data` | Any JSON-serializable data | | `event` | Custom event name (default: `"_uproot_Received"`) | | `where` | Recipient page index; `...` delivers regardless of page | ### `send_to` Send data to one or more players without a sender context. ```python send_to(recipients, data, event="EventName", where=...) ``` ### `send_to_one` Send data to a single player. ```python send_to_one(player, data, event="EventName", where=...) ``` ### `reload` Force a player’s browser to reload the current page. ```python reload(player) ``` ### `move_to_page` Move a player forward to the next occurrence of a page in their page order, skipping the pages in between. ```python move_to_page(player, TargetPage, reload_=True) ``` - If the target lies inside [SmoothOperators](https://uproot.science/building/operators.md), uproot sets them up on the way, as if the player had arrived normally: the target’s round starts, a `RandomOrder` is shuffled (pages that end up before the target are skipped), and a `Between` makes its selection. Moving into a later app starts that app. - SmoothOperators that the move skips entirely are left out. For example, moving from round 2 to a page after the `Rounds` keeps `player.round == 2`. - It raises a `ValueError` if the target is not ahead of the player, or if a `Between` on the way does not select the target. The player then stays where they are, and nothing about them changes, not even in the data. ### `move_to_end` Move a player past all remaining pages. ```python move_to_end(player, reload_=True) ``` ### `spawn` Run an async function as a supervised background task. The task keeps running after the calling method returns. Exceptions are logged, and all spawned tasks are cancelled at server shutdown. Tasks do not survive server restarts. ```python spawn(my_coroutine(player)) ``` Because spawned tasks run outside a page method, wrap data mutations in a context manager (`with player as p:`). See [Background tasks](https://uproot.science/multiplayer/real-time.md#background-tasks-with-spawn) for examples. ## Dropout functions ### `watch_for_dropout` Monitor a player for disconnection and call a handler when they go offline. ```python watch_for_dropout(player, handler, tolerance=30.0) ``` ### `mark_dropout` Add a player to the manual dropout set used by the dropout watcher. ```python mark_dropout(player_pid) ``` ## Group functions ### `create_group` Create a group from a list of players. ```python gid = create_group(session, [player1, player2], gname="custom_name", overwrite=False) ``` ### `create_groups` Create multiple groups at once. ```python gids = create_groups(session, [[p1, p2], [p3, p4]]) ``` ### `add_to_group` Add players to an existing group. ```python add_to_group(group, player) add_to_group(group, [player1, player2]) add_to_group(group, player, overwrite=True) # reassign players already in a group ``` ## The `@live` decorator Makes a page method callable from JavaScript via WebSocket. ```python class MyPage(Page): @live async def my_method(page, player, arg: str): return {"result": arg.upper()} ``` Called from JavaScript: ```javascript uproot.invoke("my_method", "hello").then(data => console.log(data.result)); ``` ## App HTTP APIs Apps may expose HTTP endpoints by defining `api(request, session)` or `api2(request, session)`. ### Operator APIs `api` is served at `/api/{appname}/{sname}/` and requires an `Authorization: Bearer ...` header matching one of the server API keys in `upd.API_KEYS`. Use it for programmatic access that should be limited to trusted operators or scripts. ### Participant APIs `api2` is served at `/api2/{appname}/{sname}/`. It is for participant-browser assets and callbacks, such as loading a captcha image. Direct requests remain public: anyone who knows the app name and session name can call the endpoint without participant credentials. !!! warning "Trust boundary" Treat an `api2` request as public unless the callback receives an authenticated `player`. Participant authentication identifies one participant; it does not grant operator privileges. Do not expose admin-only data or actions through `api2`. Use `api` for those. #### Identifying the calling participant This is an advanced feature. Use it when browser code must call an HTTP endpoint as the participant who is viewing the current page—for example, to upload data with `fetch()` while saving the result on that participant. Define `player` as an optional callback argument and reject public calls explicitly: ```python from fastapi import HTTPException async def api2(request, session, player=None): if player is None: raise HTTPException(status_code=403, detail="Participant required") data = await request.json() player.last_action = data["action"] return {"saved": True} ``` Call the endpoint from a participant template with `uproot.api2()`: ```html ``` `uproot.api2(appname, options)` accepts the usual [`fetch()` options](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch#parameters) and returns its `Promise`. It builds the URL for the current session and adds the current participant’s name and CSRF proof as request headers. It also defaults `credentials` to `"same-origin"`. Do not construct or copy these authentication headers yourself. The server handles the three credential states differently: | Credential state | Result | |------------------|--------| | Both headers absent | The public callback runs with `request` and `session`; the `player` keyword is omitted | | Both headers present and valid | The callback also receives the authenticated `player` | | One header missing, either header invalid, or the CSRF proof non-ASCII | The server returns 403 without running the callback | For an authenticated call, `request.state.uproot_player` refers to the same object as `player`. For a public call, it is `None`. The `session` and authenticated `player` remain inside their storage contexts while the callback runs, so assignments such as `player.last_action = ...` are saved normally. !!! warning "Keep the optional default" The server omits the `player` keyword entirely for a public call. Write `player=None` if a callback may receive either kind of request. Merely adding a `player` parameter does not protect the endpoint—check for `None` and return an error as shown above. !!! warning "Use only the authenticated player" Do not identify a participant from a username in the query string or request body. Those values are controlled by the caller. Read and modify only the authenticated `player` supplied by uproot. ## Utility functions ### `rng` Create an independent `random.Random` generator with an OS-random seed. Store it on a player if you need to resume the same stream later. ```python player.treatment = rng().choice(["A", "B"]) player.rng = rng() player.bomb = player.rng.randint(1, 25) ``` See [Random numbers](https://uproot.science/building/data.md#random-numbers). ### `uuid` Return a UUID (uuid7 if the Python version provides it, otherwise uuid4). ```python player.token = str(uuid()) ``` ### `cu` Create a `Decimal` from a string. Shorthand for `Decimal(value)`. ```python endowment = cu("10.00") ``` ### `safe` Mark a string as HTML-safe (will not be escaped in templates). ```python label=StringField(label=safe("Enter a value in euros")) ``` ### `data_uri` Convert binary data to a data URI string for embedding in HTML. ```python player.image_uri = data_uri(image_bytes) ``` The MIME type is inferred from common file signatures such as JPEG, PNG, GIF, PDF, ZIP, and MP4. Unknown data is emitted as `application/octet-stream`. ## Identifier types | Type | Description | |------|-------------| | `PlayerIdentifier` | Uniquely identifies a player | | `SessionIdentifier` | Uniquely identifies a session | | `GroupIdentifier` | Uniquely identifies a group | | `ModelIdentifier` | Uniquely identifies a model | These are used internally and in [custom data models](https://uproot.science/advanced/models.md). ## StorageBunch A collection of storage objects (players, groups) with query methods. | Method | Description | |--------|-------------| | `len(bunch)` | Number of items | | `bunch[i]` | Get by index | | `item in bunch` | Membership test | | `bunch.filter(*.comparisons)`{ .text-nowrap } | Filter by field values using `_` | | `bunch.find_one(**kwargs)` | Find exactly one match | | `bunch.assign(key, values)` | Set a field on all items | | `bunch.each(*keys)` | Extract fields from all items | | `bunch.apply(fn)` | Apply a function to all items | ### The `_` field referent `_` is a `FieldReferent`: a placeholder that stands for each item in the collection. It builds lazy comparison objects that are evaluated per item during `filter()`. ```python # _ is auto-imported via `from uproot.smithereens import *` cooperators = group.players.filter(_.cooperate == True) high_earners = session.players.filter(_.payoff > 10) # Multiple conditions (all must match) eligible = session.players.filter(_.present == True, _.age >= 18) # Chained attribute access same_round = session.players.filter(_.group.round == 3) ``` Supported operators: `==`, `!=`, `>`, `>=`, `<`, `<=`. Bare `_.field` (without an operator) tests for truthiness. See [Filtering with `_`](https://uproot.science/multiplayer/groups.md#filtering-with-_) for more examples. --- Source: https://uproot.science/reference/admin-api.md # Admin API reference The Admin REST API provides programmatic access to manage uproot experiments. All endpoints are located under `/admin/api/v1/` and require Bearer token authentication, except where noted. !!! note "Generated from FastAPI OpenAPI" This page is generated by `scripts/generate_admin_api_docs.py` from FastAPI’s OpenAPI schema. A running uproot server also exposes FastAPI’s live schema at `/openapi.json` and interactive documentation at `/docs` and `/redoc`. ## Authentication All requests must include an `Authorization` header with a valid API token: ```http Authorization: Bearer YOUR_API_TOKEN ``` To enable API access, add one or more tokens in your project’s `main.py`: ```python upd.API_KEYS.add("YOUR_API_TOKEN") ``` ## Errors Errors are returned as JSON with a `detail` field: ```json {"detail": "Session not found"} ``` These status codes are shared by many endpoints and are not repeated below: | Status | Meaning | |--------|---------| | `400` | The request is invalid, e.g. an unknown configuration or a duplicate name | | `401` | The Bearer token is missing or invalid | | `404` | A session, player, room, configuration, digest, or pipeline named in the request does not exist | | `422` | Parameters or request body do not match the expected types; `detail` is a list of problems | The **Responses** tables below list successful responses and errors specific to one endpoint. ## CLI access The `uproot api` command calls these endpoints from the command line: ```bash export UPROOT_API_KEY="YOUR_API_TOKEN" uproot api sessions uproot api sessions/mysession uproot api rooms uproot api rooms/waiting-room uproot api sessions/mysession/online-players uproot api sessions/mysession/players/ABC uproot api -X POST sessions -d '{"config": "myconfig", "n_players": 4}' uproot api -X PATCH sessions/mysession/active -d '{"active": false}' uproot api -X POST sessions/mysession/players/advance -d '{"unames": ["ABC"]}' ``` ## Dashboard and configurations ### `GET /admin/api/v1/configs/` List all available configurations and apps. **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `GET /admin/api/v1/configs/{cname}/` Get details for a configuration. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `cname`{ .text-nowrap } | string | Yes | | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `GET /admin/api/v1/dashboard/` Get the same top-level aggregate shown on the admin dashboard. !!! note The response contains `uproot_version`, `nudge_announcements` (whether the admin UI currently nudges you to check announcements), `configs`, `rooms`, and `active_sessions`. **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ## Sessions ### `GET /admin/api/v1/sessions/` List all sessions with their metadata. **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `POST /admin/api/v1/sessions/` Create a new session with the specified configuration and players. **Request body** (`SessionCreate`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `config`{ .text-nowrap } | string | Yes | Configuration name | | `n_players`{ .text-nowrap } | integer | Yes | Number of players to create (min: `0.0`) | | `sname`{ .text-nowrap } | string or null | No | Custom session name (auto-generated if omitted) | | `unames`{ .text-nowrap } | array[string] or null | No | Custom usernames for players | | `settings`{ .text-nowrap } | object or null | No | Session settings | | `simulate`{ .text-nowrap } | boolean | No | Enable response simulation (default: `False`) | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `201` | `application/json`{ .text-nowrap } | Successful response | --- ### `GET /admin/api/v1/sessions/{sname}/` Get detailed information about a specific session. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `PATCH /admin/api/v1/sessions/{sname}/active/` Set the active status of a session. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Request body** (`SessionActive`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `active`{ .text-nowrap } | boolean | Yes | Whether the session is active | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `PATCH /admin/api/v1/sessions/{sname}/description/` Update the description of a session. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Request body** (`DescriptionUpdate`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `description`{ .text-nowrap } | string | No | New description (empty to clear) (default: ``) | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `POST /admin/api/v1/sessions/{sname}/initialize/` Run new_session callbacks for a session that has not been initialized. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `PATCH /admin/api/v1/sessions/{sname}/settings/` Update the settings of a session. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Request body** (`SettingsUpdate`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `settings`{ .text-nowrap } | object | Yes | New settings | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `PATCH /admin/api/v1/sessions/{sname}/testing/` Set the testing mode of a session. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Request body** (`SessionTesting`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `testing`{ .text-nowrap } | boolean | Yes | Whether testing mode is enabled | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ## Players ### `GET /admin/api/v1/sessions/{sname}/multiview/` Get player metadata needed to reproduce the admin multiview. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `GET /admin/api/v1/sessions/{sname}/online-players/` Get online status and info for all players in a session. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `GET /admin/api/v1/sessions/{sname}/players/` Get specified fields for all players in a session. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Query parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields`{ .text-nowrap } | array[string] | No | | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `POST /admin/api/v1/sessions/{sname}/players/advance/` Advance specified players by one page. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Request body** (`PlayersAction`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `unames`{ .text-nowrap } | array[string] | Yes | List of usernames to act on (min items: `1`) | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `POST /admin/api/v1/sessions/{sname}/players/dropout/` Mark specified players as manually dropped out. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Request body** (`PlayersAction`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `unames`{ .text-nowrap } | array[string] | Yes | List of usernames to act on (min items: `1`) | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `POST /admin/api/v1/sessions/{sname}/players/end/` Move specified players to the end of the experiment. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Request body** (`PlayersAction`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `unames`{ .text-nowrap } | array[string] | Yes | List of usernames to act on (min items: `1`) | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `PATCH /admin/api/v1/sessions/{sname}/players/fields/` Set arbitrary fields on specified players. !!! note Field names must be valid Python identifiers (letters, digits, and underscores, not starting with a digit). They are checked before anything is written: if any name is invalid, the request fails with `400` and no player is changed. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Request body** (`PlayersFields`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `unames`{ .text-nowrap } | array[string] | Yes | List of usernames (min items: `1`) | | `fields`{ .text-nowrap } | object | Yes | Fields to set | | `reload`{ .text-nowrap } | boolean | No | Whether to trigger page reload (default: `False`) | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `POST /admin/api/v1/sessions/{sname}/players/group/` Manage group assignments for selected players. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Request body** (`PlayersGroup`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `unames`{ .text-nowrap } | array[string] | Yes | List of usernames (min items: `1`) | | `action`{ .text-nowrap } | string | Yes | Grouping action: same_group, reset, or by_size | | `group_size`{ .text-nowrap } | integer | No | Group size for by_size (min: `1.0`; default: `1`) | | `shuffle`{ .text-nowrap } | boolean | No | Shuffle players before grouping (default: `False`) | | `reload`{ .text-nowrap } | boolean | No | Whether to trigger page reload (default: `False`) | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `POST /admin/api/v1/sessions/{sname}/players/initialize/` Run new_player callbacks for players that have not been initialized. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Request body** (`PlayersAction`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `unames`{ .text-nowrap } | array[string] | Yes | List of usernames to act on (min items: `1`) | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `POST /admin/api/v1/sessions/{sname}/players/message/` Send an admin message to specified players. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Request body** (`PlayerMessage`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `unames`{ .text-nowrap } | array[string] | Yes | List of usernames (min items: `1`) | | `message`{ .text-nowrap } | string | Yes | Message to send | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `POST /admin/api/v1/sessions/{sname}/players/redirect/` Redirect specified players to an external URL. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Request body** (`PlayerRedirect`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `unames`{ .text-nowrap } | array[string] | Yes | List of usernames (min items: `1`) | | `url`{ .text-nowrap } | string | Yes | URL to redirect to (must start with http:// or https://) | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `POST /admin/api/v1/sessions/{sname}/players/reload/` Force page reload for specified players. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Request body** (`PlayersAction`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `unames`{ .text-nowrap } | array[string] | Yes | List of usernames to act on (min items: `1`) | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `POST /admin/api/v1/sessions/{sname}/players/revert/` Revert specified players by one page. !!! note Players cannot be reverted past the start of a round (`Rounds` or `Repeat`) or of an app, or from the end of the experiment, because `player.round` and `player.app` would not go back with them. All players are checked first: if any of them cannot be reverted, the request fails with `400` and no player is moved. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Request body** (`PlayersAction`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `unames`{ .text-nowrap } | array[string] | Yes | List of usernames to act on (min items: `1`) | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `POST /admin/api/v1/sessions/{sname}/players/timeout/` Adjust the page timeout for specified players. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Request body** (`PlayerTimeout`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `unames`{ .text-nowrap } | array[string] | Yes | List of usernames (min items: `1`) | | `delta`{ .text-nowrap } | number | No | Timeout adjustment in seconds (default: `60.0`) | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `GET /admin/api/v1/sessions/{sname}/players/{uname}/` Get specified fields for one player in a session. !!! note Pass `fields` repeatedly to choose fields, e.g. `?fields=id&fields=page_order`. Omitting it returns the same default fields as the all-players endpoint. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | | `uname`{ .text-nowrap } | string | Yes | | **Query parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields`{ .text-nowrap } | array[string] | No | | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ## Admin chat ### `GET /admin/api/v1/sessions/{sname}/admin-chat/` Summarize admin chat state for each player in a session. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `POST /admin/api/v1/sessions/{sname}/players/admin-chat/` Send an admin chat message to multiple players at once. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Request body** (`AdminchatBroadcast`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `unames`{ .text-nowrap } | array[string] | Yes | List of usernames (min items: `1`) | | `message`{ .text-nowrap } | string | Yes | Message to send | | `enable_replies`{ .text-nowrap } | boolean or null | No | Optionally update whether all recipients may reply | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `PATCH /admin/api/v1/sessions/{sname}/players/admin-chat/replies/` Enable or disable admin chat replies for multiple players. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Request body** (`PlayersChatReplies`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `unames`{ .text-nowrap } | array[string] | Yes | List of usernames (min items: `1`) | | `enabled`{ .text-nowrap } | boolean | Yes | Whether player replies are enabled | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `GET /admin/api/v1/sessions/{sname}/players/{uname}/admin-chat/` Get admin chat metadata and transcript for one player. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | | `uname`{ .text-nowrap } | string | Yes | | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `POST /admin/api/v1/sessions/{sname}/players/{uname}/admin-chat/` Send an admin chat message to one player. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | | `uname`{ .text-nowrap } | string | Yes | | **Request body** (`AdminchatMessage`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `message`{ .text-nowrap } | string | Yes | Message to send | | `enable_replies`{ .text-nowrap } | boolean or null | No | Optionally update whether the player may reply | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `PATCH /admin/api/v1/sessions/{sname}/players/{uname}/admin-chat/replies/` Enable or disable a player’s ability to reply in admin chat. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | | `uname`{ .text-nowrap } | string | Yes | | **Request body** (`AdminchatReplies`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `enabled`{ .text-nowrap } | boolean | Yes | Whether player replies are enabled | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ## Data export ### `GET /admin/api/v1/sessions/{sname}/data/` Get all session data in display format, optionally filtered by timestamp. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Query parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `since`{ .text-nowrap } | number | No | Only return data updated since this epoch timestamp | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `GET /admin/api/v1/sessions/{sname}/data/export/` Download a ZIP briefcase of session data, as in the admin UI. The briefcase always contains the ultralong, sparse, and latest formats, page times, a data dictionary, and integrity checksums. Passing gvar adds a grouped latest format on top. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Query parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `filetype`{ .text-nowrap } | string | No | Export file type: csv or jsonl | | `gvar`{ .text-nowrap } | array[string] | No | Group-by variables for the optional grouped latest format | | `filters`{ .text-nowrap } | boolean | No | Apply reasonable filters | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/zip`{ .text-nowrap } | ZIP briefcase | --- ### `GET /admin/api/v1/sessions/{sname}/data/jsonl/` Download session data as JSONL (streaming). **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Query parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `format`{ .text-nowrap } | string | No | Export format: ultralong, sparse, or latest | | `gvar`{ .text-nowrap } | array[string] | No | Group-by variables | | `filters`{ .text-nowrap } | boolean | No | Apply reasonable filters | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/jsonl`{ .text-nowrap } | JSONL stream | --- ## Digests and pipelines ### `GET /admin/api/v1/sessions/{sname}/digests/` Run all available app digests for a session. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `GET /admin/api/v1/sessions/{sname}/digests/html/` Render the app-authored AdminDigest.html fragments shown by the admin UI. !!! note `apps` lists every app with a digest. `html` only contains entries for apps that provide an `AdminDigest.html` template. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `GET /admin/api/v1/sessions/{sname}/digests/{appname}/` Run one app digest for a session. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | | `appname`{ .text-nowrap } | string | Yes | | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `GET /admin/api/v1/sessions/{sname}/digests/{appname}/html/` Render one app-authored AdminDigest.html fragment. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | | `appname`{ .text-nowrap } | string | Yes | | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `text/html`{ .text-nowrap } | Rendered fragment | --- ### `GET /admin/api/v1/sessions/{sname}/pipelines/` List apps that provide a pipeline for a session. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `GET /admin/api/v1/sessions/{sname}/pipelines/html/` Render app-authored AdminPipeline.html fragments shown by the admin UI. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `GET /admin/api/v1/sessions/{sname}/pipelines/{appname}/html/` Render one app-authored AdminPipeline.html fragment. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | | `appname`{ .text-nowrap } | string | Yes | | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `text/html`{ .text-nowrap } | Rendered fragment | --- ### `GET /admin/api/v1/sessions/{sname}/pipelines/{appname}/runs/` Run an app pipeline without custom JSON data, matching the admin UI button. !!! note This endpoint never passes data to the pipeline, even if you send a request body. Use `POST` to pass data. !!! note If the pipeline returns a custom data export, it is downloaded as CSV or JSONL, depending on `filetype`. Any other result is returned as plain text. `filetype` must be `csv` or `jsonl`; any other value fails with `400` before the pipeline runs. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | | `appname`{ .text-nowrap } | string | Yes | | **Query parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `filetype`{ .text-nowrap } | string | No | Export file type: csv or jsonl | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `text/plain`{ .text-nowrap } | Pipeline result | | `200` | `text/csv`{ .text-nowrap } | Custom data export with `filetype=csv` | | `200` | `application/jsonl`{ .text-nowrap } | Custom data export with `filetype=jsonl` | --- ### `POST /admin/api/v1/sessions/{sname}/pipelines/{appname}/runs/` Run an app pipeline, optionally passing a JSON request body. !!! note This endpoint accepts an optional JSON request body. The decoded body is passed to the app’s `pipeline()` as `data` (`None` if the body is empty). A body that is not valid JSON fails with `400`. !!! note If the pipeline returns a custom data export, it is downloaded as CSV or JSONL, depending on `filetype`. Any other result is returned as plain text. `filetype` must be `csv` or `jsonl`; any other value fails with `400` before the pipeline runs. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sname`{ .text-nowrap } | string | Yes | | | `appname`{ .text-nowrap } | string | Yes | | **Query parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `filetype`{ .text-nowrap } | string | No | Export file type: csv or jsonl | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `text/plain`{ .text-nowrap } | Pipeline result | | `200` | `text/csv`{ .text-nowrap } | Custom data export with `filetype=csv` | | `200` | `application/jsonl`{ .text-nowrap } | Custom data export with `filetype=jsonl` | --- ## Rooms ### `GET /admin/api/v1/rooms/` List all rooms with their configuration. **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `POST /admin/api/v1/rooms/` Create a new room. **Request body** (`RoomCreate`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `name`{ .text-nowrap } | string | Yes | Room name (min length: `1`) | | `config`{ .text-nowrap } | string or null | No | Default configuration for sessions | | `labels`{ .text-nowrap } | array[string] or null | No | Allowed labels for participants | | `capacity`{ .text-nowrap } | integer or null | No | Maximum capacity | | `open`{ .text-nowrap } | boolean or null | No | Whether the room is open for joining (defaults to true if sname is given, false otherwise) | | `sname`{ .text-nowrap } | string or null | No | Associated session name | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `201` | `application/json`{ .text-nowrap } | Successful response | --- ### `GET /admin/api/v1/rooms/{roomname}/` Get detailed information about a specific room. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `roomname`{ .text-nowrap } | string | Yes | | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `PATCH /admin/api/v1/rooms/{roomname}/` Update room settings, optionally associating an existing session (only when no session is currently associated). **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `roomname`{ .text-nowrap } | string | Yes | | **Request body** (`RoomUpdate`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `config`{ .text-nowrap } | string or null | No | Default configuration | | `labels`{ .text-nowrap } | array[string] or null | No | Allowed labels | | `capacity`{ .text-nowrap } | integer or null | No | Maximum capacity | | `open`{ .text-nowrap } | boolean or null | No | Whether the room is open (defaults to true if sname is given, otherwise unchanged) | | `sname`{ .text-nowrap } | string or null | No | Existing session to associate with the room | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `DELETE /admin/api/v1/rooms/{roomname}/` Delete a room (only when no session is associated). **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `roomname`{ .text-nowrap } | string | Yes | | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `PATCH /admin/api/v1/rooms/{roomname}/capacity/` Set a room’s capacity, even while a session is associated. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `roomname`{ .text-nowrap } | string | Yes | | **Request body** (`RoomCapacity`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `capacity`{ .text-nowrap } | integer or null | Yes | Maximum capacity (null for unlimited) | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `POST /admin/api/v1/rooms/{roomname}/close/` Close a room, optionally disassociating its session first. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `roomname`{ .text-nowrap } | string | Yes | | **Request body** (`RoomClose`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `disassociate`{ .text-nowrap } | boolean | No | If true, disassociate the session before closing (default: `False`) | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `GET /admin/api/v1/rooms/{roomname}/online/` Get online status for a room’s waiting area. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `roomname`{ .text-nowrap } | string | Yes | | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `PATCH /admin/api/v1/rooms/{roomname}/open/` Set a room’s open status without requiring disassociation. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `roomname`{ .text-nowrap } | string | Yes | | **Request body** (`RoomOpen`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `open`{ .text-nowrap } | boolean | Yes | Whether the room should be open | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `POST /admin/api/v1/rooms/{roomname}/sessions/` Create a new session within a room, by default using the room’s config. !!! note If `config` is omitted, the room’s default configuration is used. If the room has none either, the request fails with `400`. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `roomname`{ .text-nowrap } | string | Yes | | **Request body** (`RoomSessionCreate`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `config`{ .text-nowrap } | string or null | No | Configuration name (defaults to the room’s config) | | `n_players`{ .text-nowrap } | integer | Yes | Number of players (min: `0.0`) | | `assignees`{ .text-nowrap } | array[string] or null | No | Labels to assign to players | | `settings`{ .text-nowrap } | object or null | No | Session settings | | `sname`{ .text-nowrap } | string or null | No | Custom session name | | `unames`{ .text-nowrap } | array[string] or null | No | Custom usernames | | `no_grow`{ .text-nowrap } | boolean | No | Lock capacity to n_players (default: `False`) | | `simulate`{ .text-nowrap } | boolean | No | Enable response simulation (default: `False`) | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `201` | `application/json`{ .text-nowrap } | Successful response | --- ### `DELETE /admin/api/v1/rooms/{roomname}/sessions/` Disassociate a room from its current session. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `roomname`{ .text-nowrap } | string | Yes | | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ## System ### `GET /admin/api/v1/announcements/` Fetch announcements from upstream. **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `POST /admin/api/v1/announcements/dismiss/` Silence the admin UI’s nudge to check announcements. !!! note The nudge stays silent for ten years. The dashboard’s `nudge_announcements` reflects this. **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `POST /admin/api/v1/auth/login/` Create the same browser admin session token as submitting /admin/login/. !!! note This endpoint does not require a Bearer token. !!! note Login attempts are rate-limited per IP address. After 50 failed attempts within one hour, the IP is blocked for six hours. Requests from localhost are exempt. **Request body** (`AuthLogin`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `user`{ .text-nowrap } | string | No | Admin username (default: `admin`) | | `pw`{ .text-nowrap } | string | No | Admin password (default: ``) | | `token`{ .text-nowrap } | string | No | Auto-login token (default: ``) | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `201` | `application/json`{ .text-nowrap } | Successful response | | `401` | `application/json`{ .text-nowrap } | Invalid admin credentials | | `429` | `application/json`{ .text-nowrap } | Too many failed login attempts | --- ### `POST /admin/api/v1/auth/logout-all/` Revoke all browser admin sessions for the token’s user, matching /admin/status/logout-all/. !!! note This revokes browser admin-login sessions. It does not revoke API keys. **Request body** (`AuthToken`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `auth_token`{ .text-nowrap } | string | Yes | Value of the uauth browser cookie | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `POST /admin/api/v1/auth/logout/` Revoke one browser admin session token, matching /admin/logout/. !!! note This revokes browser admin-login sessions. It does not revoke API keys. **Request body** (`AuthToken`): | Field | Type | Required | Description | |-------|------|----------|-------------| | `auth_token`{ .text-nowrap } | string | Yes | Value of the uauth browser cookie | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `GET /admin/api/v1/auth/sessions/` Get information about active authentication sessions. **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `DELETE /admin/api/v1/auth/sessions/{user}/` Revoke all browser admin sessions for one user. !!! note This revokes browser admin-login sessions for the named user. It does not revoke API keys. **Path parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `user`{ .text-nowrap } | string | Yes | | **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- ### `GET /admin/api/v1/database/dump/` Download a complete machine-readable database dump. !!! note The response is a gzip-compressed MessagePack dump intended for `uproot restore`, not JSON. **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/gzip`{ .text-nowrap } | Gzip-compressed database dump | --- ### `GET /admin/api/v1/praise/` Fetch the same praise text shown by the admin UI. **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `text/plain`{ .text-nowrap } | Praise text | | `502` | `application/json`{ .text-nowrap } | Praise could not be fetched from upstream | --- ### `GET /admin/api/v1/project/archive/` Download a reproducible .tar.gz archive of the project code, excluding files ignored by .gitignore. **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/gzip`{ .text-nowrap } | Gzip-compressed tar archive of the project | --- ### `GET /admin/api/v1/status/` Get status information. **Responses**: | Status | Content | Description | |--------|---------|-------------| | `200` | `application/json`{ .text-nowrap } | Successful response | --- --- Source: https://uproot.science/reference/cli.md # CLI commands uproot provides a command-line interface for managing projects and running experiments. Commands are split into two categories: **global commands** that work anywhere, and **project commands** that must be run inside a project directory. ## Global commands ### uproot setup Create a new uproot project. ```bash uproot setup my_project ``` | Option | Description | |--------|-------------| | `--force` | Overwrite existing files | | `--minimal` | Create a minimal project without the example app | | `--no-example`{ .text-nowrap } | Skip the example app | ### uproot api Access the [Admin REST API](https://uproot.science/reference/admin-api.md) from the command line. ```bash # List sessions uproot api sessions # Get session details uproot api sessions/mysession # Create a session uproot api -X POST sessions -d '{"config": "myconfig", "n_players": 4}' # Access a remote server uproot api -u https://example.com/ sessions ``` | Option | Default | Description | |--------|---------|-------------| | `--url`, `-u` | `http://127.0.0.1:8000/` | Server base URL | | `--auth`, `-a` | `$UPROOT_API_KEY` | Bearer token | | `--method`, `-X` | `GET` | HTTP method | | `--data`, `-d` | — | JSON request body | ### uproot check-translations Check the [translations](https://uproot.science/building/pages.md#translations) of a project. For each language that has a YAML file in the project, it lists every phrase that has no translation, either in the project or among uproot’s built-in translations. ```bash # Check the project in the current directory uproot check-translations # Check another directory, such as a single app uproot check-translations my_project/my_app ``` It finds phrases in `{% translate %}` blocks, in `_("...")` calls in templates and JavaScript, in `lookup("...")` calls, and in the labels, descriptions, and choices of form fields. It also points out phrases that differ from a translated one only in quotes or spacing. uproot translates all form field texts, even those not meant to be translated, such as the names of languages in a language selector. So a field text only counts as missing if it is translated for some languages but not for others. The command exits with status 1 if phrases are missing. | Option | Description | |--------|-------------| | `--untranslated` | List form field texts that have no translation in any language | ### uproot --version Show the installed uproot version. ### uproot --copyright Show copyright information. ## Project commands These commands must be run from inside an uproot project directory (where `main.py` is located). ### uproot run Start the development server. ```bash uproot run ``` | Option | Default | Description | |--------|---------|-------------| | `-h`, `--host` | `127.0.0.1` | Host to bind to | | `-p`, `--port` | `8000` | Port to listen on | | `--unsafe` | — | Disable HTTPS requirement (for development behind certain proxies) | | `--public-demo`{ .text-nowrap } | — | Run in public demo mode (restricted admin) | ### uproot start Start the development server with a participant link ready to go. This is the fastest way to try an experiment: instead of creating a session in the admin by hand, uproot creates an open [room](https://uproot.science/running/rooms.md) for your config and prints its URL when the server starts. ```bash uproot start myconfig ``` ``` Room: http://127.0.0.1:8000/room/quick1/ ``` Open the room URL in one browser tab per participant. Each tab joins the session as a new player. If your project has exactly one config, you can omit the config name and just run `uproot start`. The rooms created this way are ordinary rooms named `quick1`, `quick2`, and so on; each `uproot start` creates a new one, and they appear under **Rooms** in the admin like any other. It accepts the same `--host`, `--port`, `--unsafe`, and `--public-demo` options as `uproot run`, plus: | Option | Description | |--------|-------------| | `CONFIG` or `--config`{ .text-nowrap } | Config to use (optional if the project has exactly one config) | | `--simulate`{ .text-nowrap } | Enable the app’s `simulate.js` responses for the quick room’s session (see [App testing](https://uproot.science/running/admin.md#app-testing)) | ### uproot reset Reset the database, deleting all sessions and data. ```bash uproot reset ``` | Option | Description | |--------|-------------| | `--yes` | Skip the confirmation prompt | !!! warning This permanently deletes all experiment data. Use `uproot dump` first if you need a backup. ### uproot dump Dump the entire database to a file. ```bash uproot dump --file backup.msgpack.gz ``` | Option | Description | |--------|-------------| | `--file` | Path to the output file (required) | The output is gzip-compressed automatically. ### uproot restore Restore a database from a dump file. ```bash uproot restore --file backup.msgpack.gz ``` | Option | Description | |--------|-------------| | `--file` | Path to the dump file (required) | | `--yes` | Skip the confirmation prompt | `uproot restore` accepts both gzip-compressed and uncompressed dump files. ### uproot new Create a new app in the current project. ```bash uproot new my_app ``` | Option | Description | |--------|-------------| | `--minimal`{ .text-nowrap } | Create a minimal app without example code | This creates a new directory with `__init__.py`, the page templates, and `simulate.js`. Without `--minimal`, the new app is the two-player prisoner’s dilemma from the [tutorial](https://uproot.science/getting-started/tutorial.md), ready to run. With `--minimal`, it has a single placeholder page. You still need to register the app in `main.py` using `load_config`. ### uproot newpage Create a new page in an existing app. ```bash uproot newpage my_app MyNewPage ``` This creates a new HTML template file for the page and adds the page class to the app’s `__init__.py`. ### uproot examples Download the example experiments from GitHub. ```bash uproot examples ``` Downloads and extracts all example apps into the current directory. Useful for learning and reference. ### uproot announcements Check whether the uproot developers have posted important announcements for your version. ```bash uproot announcements ``` This is the only command that contacts uproot.science, and only when you run it. It respects `upd.UPSTREAM = False` in `main.py` (see [Announcements](https://uproot.science/running/admin.md#announcements)). ### uproot deployment Print the currently set `UPROOT_*` environment variables. ```bash uproot deployment ``` ## Using with uv If you are using uv (recommended), prefix commands with `uv run`: ```bash uv run uproot run uv run uproot new my_app uv run uproot dump --file backup.msgpack.gz ```