How to read this page
- Every step names the tool or the part of Munitas where it happens. The label under the title says where, and the step reads in the same order each time: what is happening, the evidence, and then what to look for in it.
- Console steps happen in the Munitas console, the web app that people open in a browser. They show real screenshots, and clicking one enlarges it.
- Python steps happen in Python, on the person’s own computer, in a notebook or in a terminal. Python is a window where a person types a line and sees the answer straight away. From there the person uses the Munitas client library, which sends requests to Munitas, and DuckDB, a free tool for analysing tables. Each dark box on the page is one of these steps.
- In a dark box, the top part is exactly what was typed and the bottom part is exactly what came back.
meis the client library signed in as the person named on the label, andcustodianis the client library signed in as the custodian. - Every step was run for real by a script that types each one, so the answers are genuine and nothing has been edited. Every name of a person, patient or card holder in the example data is invented.
Words used on this page
- Organisation
- A company or hospital group that uses Munitas. Each organisation sees only its own data.
- Department
- A team inside an organisation that owns some of its data, such as Cardiology.
- Dataset
- A named collection of records, such as a table of patient admissions.
- Custodian
- A person who holds the data custodian role, which allows deciding who may read data. A custodian decides for the departments they are an approver for.
- Access level
- How restricted a dataset is. Raw is the most restricted, and nobody may read it without permission. Published is the most open.
- Lease
- Permission, given by the custodian, to read one dataset for one stated purpose and for a limited time.
- Query
- A question about a dataset, written in a language called SQL.
- Sensitivity label
- How identifying a column is. none does not identify anybody, quasi is a detail that could help identify a person when combined with others, and phi is protected health information.
- Token
- A short-lived password that also states why the person wants to read.
- Sealed
- Finished and closed for good, so that it can never be edited.
- Iceberg table
- An open way of storing a table that tools such as DuckDB can read directly.
Signing a notebook in
Sam, a researcher, does the readmission work in a Python notebook, which is a document that mixes code with the results of running it. A notebook is never given Sam's password or Sam's console sign-in, because either would let it do everything Sam can, including the things Sam should only ever do on screen, such as deciding a request. A notebook gets a pass of its own instead, which is a short-lived key that stands for one signed-in notebook and reaches much less.
The notebook asks Munitas for a code, shows it with an address, and waits. Nothing is signed in yet, and nothing has been given to the notebook. The notebook gives itself a name, so that Sam can tell it apart from another one later.
Munitas.sign_in is the Munitas client library asking Munitas for a code, and then waiting for the person to approve it in the console.me = Munitas.sign_in(API, label="Sam's readmission notebook", wait=180)What came back
To sign this notebook in as you, open http://localhost:4444/oauth2/device/verify?user_code=FGMFNQGC and type the code FGMFNQGC. Check that the notebook it names is "Sam's readmission notebook". It waits for you up to 10 minutes.
Sam opens the address the notebook showed, in the console where Sam is already signed in, and types the code. Typing it proves that the person at the console is also the person at the notebook. Somebody who did not just start a sign-in has nothing to do on this page.
Before approving, Sam is told which notebook is asking, from which address, with which program, and for how long the sign-in can last. The page lists what the notebook will be able to do as Sam and, just as plainly, what it will not.
Sam presses Approve. The notebook, which has been asking every few seconds whether Sam has answered, now receives its pass. The pass lasts 15 minutes and renews itself, up to the 8 hours Sam saw, for as long as nobody ends the sign-in.
The same line of code that was waiting has finished, and the notebook holds its pass. It asks who it is signed in as, and finds a dataset by name, which Sam may do.
me is the Munitas client library, a small Python package that asks Munitas for things on the person’s behalf, signed in as Sam.who = me.me
print(f"Signed in as {who['label']} in the {who['tenant_id']} organisation")
found = me.dataset("diagnosis_codes")
print(found["name"], "has", found["version_count"], "version, and Sam may read it")What came backSigned in as Sam in the health organisation diagnosis_codes has 1 version, and Sam may read it
What the pass cannot do, and ending it
A notebook that could do everything its person can would be a risk if it were copied or left behind. So the pass is limited, and the person can end it at any time.
A notebook may find datasets, ask for access, open the few files its person was allowed to open, and make a dataset from a query. Deciding a request, or changing a role, is done in the console. Sam tries to approve a request from the notebook.
me is the Munitas client library, a small Python package that asks Munitas for things on the person’s behalf, signed in as Sam.Names used here that are not defined in this box: MunitasError is the error the client library raises when Munitas refuses a request.try:
me.approve("any-request-at-all")
except MunitasError as exc:
print("Refused:", exc)What came backRefused: HTTP 403: a notebook sign-in reaches only what the client library does: finding datasets, asking for access, opening the few files you were allowed, and making a dataset from a query. Anything else, such as deciding a request, is done in the console
In the console, the page called Your notebooks lists each notebook that signed in as Sam: its name, when it started, until when it can last at most, when it was last used and from which address.
Sam presses End now. Because the notebook was used a moment ago, the page asks before it ends something that may be in the middle of work.
Sam answers yes. The pass stops working at the notebook's very next request, and the renewal that would have kept it going stops too.
Back in the notebook, the same kind of request that worked a minute ago is refused. To go on, Sam would sign the notebook in again, with a new code.
me is the Munitas client library, a small Python package that asks Munitas for things on the person’s behalf, signed in as Sam.Names used here that are not defined in this box: MunitasError is the error the client library raises when Munitas refuses a request.try:
me.dataset("diagnosis_codes")
except MunitasError as exc:
print("Refused:", exc)What came backRefused: HTTP 401: this notebook sign-in is not in force. Sign in again from the notebook