# Tumor Model Explorer — Product Requirements (v1.0)

Tumor Model Explorer is a public research catalogue of 372 patient-derived childhood solid-tumour models described by 24 attributes. Researchers search and filter the catalogue in a grid that loads rows from the server in blocks of 100, sort it, export it to CSV, open a detail drawer for each model and submit and withdraw requests for models.

**Problem.** Researchers choose models for experiments from a very wide and long table. If the count, the rows, the sort or the export is wrong, they pick the wrong models or miss suitable ones. The catalogue must expose every model and attribute exactly once and answer every filter with exactly the right rows.

## Users
- **Researcher** — Find models with specific diagnosis, age, sex, status and availability, export them and request material.
- **Catalogue curator** — Be sure that what the grid, the count and the export show is the true catalogue.

## Goals
- The results count equals the number of rows the grid can show and the number of rows exported.
- Every model appears exactly once and every attribute is visible.
- Filters, search and sort return exactly the right rows and are reproducible from a link.
- A request can be made for at most 10 models and withdrawn while still submitted.

## Results grid (GRD)

A virtualised grid shows all models with 24 attribute columns and a frozen sample-name column.

- **FR-GRD-01** (Must) The results count equals the number of distinct model rows the grid can show, including rows beyond the first server block.
  - The unfiltered catalogue reads "372 results" and exposes 372 rows with 372 distinct O-PDX Sample Names.
  - The last row in the default order is PXOS-4592_X1.
- **FR-GRD-02** (Must) The grid shows all 24 data columns in the catalogue order plus a Select column, with the sample name pinned on the left while scrolling horizontally.
  - Columns in order: O-PDX Sample Name, Disease, Age, Sex, Status, Location, Common Mutations, Treated, RMS subtype/fusion, Known Metastatic Site(s), NMYC Amplified, HLA-A.a1, HLA-A.a2, HLA-B.a1, HLA-B.a2, HLA-C.a1, HLA-C.a2, Germline Mutation, Matched Sequence (WGS) Available, Matched RNASeq available (O-PDX and Patient tumor), 3D-spheroid, 2D-adapted, Cell Line, iPSC.
- **FR-GRD-03** (Must) Age sorts numerically; clicking the Age header cycles ascending, descending and back to the default order, and the header shows the direction.
  - First click: ▲ with PXRB-8450_X1 (0.3) first.
  - Second click: ▼ with PXSS-8291_X2 (20.8), PXRHB-6855_X2 (20.8), PXSS-3842_X2 (20.7) first.
  - Third click: no arrow and the default order returns with PXSS-8614_X1 first.
- **FR-GRD-04** (Could) Filter and sort state is kept in the URL so a reload or a shared link reproduces the view; "Clear all filters" also clears the sort.
  - Ewing sarcoma ticked and Age ascending survive a reload: "46 results" and Age still ▲.
  - "Clear all filters" gives "372 results", no ticks and no sort.

## Facets, age range and search (FLT)

Facets, an age range and free-text search narrow the catalogue.

- **FR-FLT-01** (Must) Facets from different groups combine with AND, and facet counts react to the other groups.
  - Disease Neuroblastoma gives "58 results" with Sex Male 33 and Female 25.
  - Adding Sex Female gives "25 results", every row Neuroblastoma and Female.
  - Osteosarcoma, Female and Relapse yields exactly 4 models: PXOS-0613_X3, PXOS-6135_X1, PXOS-6910_X1, PXOS-5922_X3.
- **FR-FLT-02** (Must) Several values of one facet are OR-ed and widen the result set.
  - Wilms tumor and Hepatoblastoma together give "60 results" (40 plus 20).
- **FR-FLT-03** (Should) The age range is inclusive at both ends and can leave either end empty.
  - Min 5 and Max 10 give "96 results", every age from 5 to 10 inclusive.
  - Max 1 with Min empty gives "9 results", all Retinoblastoma or Neuroblastoma.
- **FR-FLT-04** (Should) An invalid age range is refused with a message instead of returning nothing.
  - Min 9 and Max 3 shows "Minimum age cannot be greater than maximum age".
  - Min "abc" shows "Minimum age must be a number".
- **FR-FLT-05** (Should) Free-text search matches any column case-insensitively and an empty result says so.
  - "alk" gives "24 results", every row with ALK in Common Mutations.
  - "zzzz" gives "0 results" and "No models match these filters."
- **FR-FLT-06** (Should) Values in columns the facets do not cover can be read accurately across all rows.
  - 18 models have iPSC "Yes".
  - Rhabdomyosarcoma ("64 results") has Alveolar (PAX3-FOXO1) 15, Alveolar (PAX7-FOXO1) 17, Spindle cell (MYOD1) 11, Embryonal 10 and Embryonal (fusion-negative) 11.

## CSV export and detail drawer (EXP)

The current result can be exported and each model opened in a drawer.

- **FR-EXP-01** (Must) Export CSV contains a header with the 24 column labels and every row matching the current filters, not only the first block of 100.
  - With Wilms tumor filtered ("40 results") the file has the header and 40 data rows.
  - With no filters the file has 372 data rows, matching "372 results".
- **FR-EXP-02** (Should) Clicking a sample name opens a dialog listing the model's attributes, and Escape closes it.
  - PXOS-4592_X1 opens a dialog titled PXOS-4592_X1 listing 23 attributes including Osteosarcoma, 15.8, Male, Diagnosis, Pelvis, Germline Mutation TP53 and iPSC No.
  - Escape closes the dialog and shows the grid.

## Model requests (REQ)

Researchers request up to 10 models and withdraw submitted requests.

- **FR-REQ-01** (Must) Selected models can be requested through a form; a submitted request appears first in My requests with status Submitted.
  - Selecting PXSS-8614_X1 and PXOS-4234_X2 enables "Request selected (2)", and the request page lists both.
  - Submitting with the material transfer terms accepted shows "Request RQ-2 submitted" with 2 models.
  - My requests lists RQ-2 first (Submitted, 2 models) above RQ-1 (Under review).
- **FR-REQ-02** (Should) Every required request field reports its own message.
  - Empty submit: "Enter your full name", "Enter your email address", "Enter your institution", "Describe the intended use in at least 20 characters", "You must accept the material transfer terms".
  - Email "rae@lab" shows "Enter a valid email address".
  - With the model removed it shows "Select at least one model".
- **FR-REQ-03** (Should) At most 10 models can be selected for one request.
  - Ten ticked rows give "Request selected (10)".
  - An eleventh shows "You can select at most 10 models", stays unticked and the button still says 10.
- **FR-REQ-04** (Should) Only a Submitted request can be withdrawn, after confirmation.
  - Withdraw on RQ-2 asks "Withdraw RQ-2?" with Withdraw and Keep; Withdraw sets the status to Withdrawn and removes its button.
  - RQ-1 (Under review) offers no Withdraw button.

## Search API (API)

The API exposes the same data and rules as the grid.

- **FR-API-01** (Should) The search API pages and filters like the grid and refuses unknown sorts, unknown models and over-sized requests.
  - /api/genome/search?offset=300&limit=100 returns 200 with total 372 and 72 rows.
  - /api/genome/search?disease=Neuroblastoma&sex=Female returns total 25.
  - sort=nope returns 422 "Unknown sort column \"nope\"".
  - /api/genome/model/NOPE returns 404 "No model named \"NOPE\"".
  - A request with 11 samples returns 422 with errors.samples "You can request at most 10 models per request".

## Non-functional requirements

- **NFR-01** (Must) Rows are loaded from the server in blocks of 100 as the user scrolls without losing, repeating or reordering any row.
  - The 372 rows seen across all blocks are 372 distinct models.
- **NFR-02** (Should) The catalogue is public and needs no sign-in.

## Glossary and rules

- **Model** — A patient-derived tumour model identified by its O-PDX Sample Name.
- **Facet** — A filter group with selectable values and counts.
- **Withdrawn** — The status of a request cancelled by the researcher.

## Out of scope

- Real specimen shipping
- Authentication (the catalogue is public)