@@ -1,3 +1,45 @@
+# sondavi 0.9.0
+
+## Scale scores of the questionnaire, worked out again
+
+* `scale(data, score="sdq_emo")` works out a scale score the questionnaire computes itself
+  (Σ in the editor): the codebook now says which rows it counts - those of its subscales, in a
+  loop those of the same copy -, mean or sum, and how many have to be answered. That is the
+  way to give responses recorded before a score was added or changed the score of now; the
+  platform keeps every response's score as it was computed then. Needs a platform that
+  describes its scale scores (version 0.106 or later); with an older one, name the items.
+* `scale()` takes `method="sum"` as well as the mean, and gives whole numbers as the platform
+  writes them (4, not 4.0) for rows.
+* The codebook carries `subscale` on a matrix row and `scale_score` on a scale score.
+
+## Questions with several answers
+
+* `options()` gives one field per option of a multiple-choice question, a tag box, a picture
+  choice or a ranking, as the export files have them: 1 when the option was chosen, 0 when the
+  question was answered without it, None when it was not answered; for a ranking the option's
+  place. In a frame the columns are integers that can be missing (`Int64`).
+* `unnest()` adds those fields right after the list (`options=False` leaves them out).
+
+## Tested against more of what researchers ask
+
+The tests now include a study with multiple choice ("None", "Other" with its text), a tag box,
+a ranking, a rating, yes/no, a drop-down with "Don't know", text boxes, a constant sum with its
+total, an SDQ-like matrix with subscales and the questionnaire's own scale scores, and a loop
+with a score per copy - recorded from the platform, and checked value by value against the
+platform's own export file. The platform's scale score cases now include sums.
+
+## The files participants uploaded
+
+`con.files(survey_id)` downloads the files of a study's "File Upload" questions and unpacks
+them: a folder per question, the files named by response (`drawing/1234-1.png`) rather than by
+the name a participant gave them, and a list with one row per file - whose it is
+(`response_id`, and `respondent_id` where your token may read it), the original name, type,
+size, checksum and `local_path`, where the file now is. Join it to `responses()` over
+`response_id`.
+
+In the responses themselves an uploaded file now appears as its name, type, size and a
+reference; the file is no longer in the row.
+
 # sondavi 0.8.0
 
 ## Verifying a certified dataset
 
@@ -80,6 +80,46 @@ In a frame the items are Categoricals, and their codes are positions, not answer
 "Don't know" and other answers that are no number count as missing here; by default every
 item has to be answered, so a mean over fewer items never happens unnoticed.
 
+A scale score the questionnaire computes itself (Σ in the editor, with subscales if the matrix
+rows have them) is stored with each response as it was computed then. To work it out again — for
+responses recorded before you added or changed it — name it; the codebook supplies its rows,
+mean or sum, and its minimum. `method="sum"` adds instead of averaging when you name the items
+yourself:
+
+```python
+df["sdq_emo_now"] = scale(df, score="sdq_emo")                # the emotional subscale, summed
+scale(flat, ["sdq.e1", "sdq.e2"], codebook=cb, method="sum")   # the same by hand
+```
+
+`score=` needs a platform that describes its scale scores in the codebook (version 0.106 or later).
+
+## Questions with several answers
+
+A multiple-choice answer, a tag box or a ranking arrives as the list of options chosen and stays
+one field. `unnest()` adds one field per option right after it, as the export files have them —
+1 chosen, 0 answered without it, None (NA in a frame) not answered; for a ranking the option's
+place. `options(rows, codebook=cb)` does the same without unnesting anything else.
+
+```python
+flat = unnest(con.frame(42))
+flat["devices.phone"].value_counts()
+```
+
+## Uploaded files
+
+A "File Upload" answer in the responses is the file's name, type, size and a reference; the
+files themselves come with `files()`:
+
+```python
+files = con.files(42)                  # unpacked into sondavi-files-42/
+drawings = [f for f in files if f["question"] == "drawing"]
+drawings[0]["local_path"]
+```
+
+A folder per question, the files named by response (`drawing/1234-1.png`), never by the name
+a participant gave them — so the drawings of one task can be rated without seeing whose they
+are. Join to the responses over `response_id`.
+
 ## Image marking
 
 An image marking question (participants paint areas or set pins on a map or picture) arrives
 
@@ -1,6 +1,6 @@
 [project]
 name = "sondavi"
-version = "0.8.0"
+version = "0.9.0"
 description = "Read your own study data from the Sondavi survey platform"
 readme = "README.md"
 requires-python = ">=3.9"
 
@@ -17,10 +17,10 @@
     print(verify("study.csv", "study.certificate.json"))
 """
 
-from .client import Connection, ApiError, connect, unnest, markings, conversations, items, scale
+from .client import Connection, ApiError, connect, unnest, options, markings, conversations, items, scale
 from .snapshots import Snapshot
 from .certificates import Verification, verify
 
-__all__ = ["connect", "Connection", "ApiError", "Snapshot", "unnest", "markings", "conversations", "items", "scale",
+__all__ = ["connect", "Connection", "ApiError", "Snapshot", "unnest", "options", "markings", "conversations", "items", "scale",
            "verify", "Verification"]
-__version__ = "0.8.0"
+__version__ = "0.9.0"