Cirro is a cloud platform where research groups keep their scientific data, run analysis pipelines on it, and share results. Institutions run their own Cirro environments, and researchers work inside projects in them. An app built on Cirro signs a researcher in and works with their projects on their behalf.
This page is the vocabulary the rest of the kit assumes.
flowchart TD
tenant["Tenant<br/>(an institution's Cirro environment)"]
project["Project<br/>members, roles, storage, billing"]
dataset["Dataset<br/>a set of files + metadata"]
files["Files"]
other["Sheets, workspaces,<br/>references, notes"]
tenant --> project
project --> dataset --> files
project --> other
pipeline["Pipeline run"] -- "reads datasets,<br/>writes a new dataset" --> dataset
| Term | What it means |
|---|---|
| Tenant | An independent Cirro environment, usually run for one institution, with its own users, projects, sign-in and web address. There is also a public Cirro tenant. Apps are connected to tenants one at a time; see connecting to tenants. |
| Project | The unit of work and access. A project has members, storage for its data, a billing account for the compute it uses, and everything below lives in one. Most API calls take a projectId. |
| Role | A member's level of access in a project: OWNER, ADMIN, CONTRIBUTOR or COLLABORATOR. The same person can have different roles in different projects. See permissions. |
| Dataset | A collection of files with a name, description, tags and status. Datasets are created by uploading files or by running a pipeline. processId records what kind of data it is or which pipeline made it, and sourceDatasetIds links pipeline outputs to their inputs. |
| Files and manifest | A dataset's files are listed in its manifest. Apps don't get permanent links to files: they get short-lived credentials or signed URLs at the moment of use. See working with files. |
| Pipeline (process) | An analysis workflow, typically Nextflow or Cromwell, that runs on Cirro's compute. The API calls pipelines processes; the same term also covers the data types used when uploading. |
| Analysis (execution) | One run of a pipeline on one or more datasets. It produces a new dataset, and the API reports its tasks, logs and cost. |
| Samples and metadata | Per-sample information (for example tissue, condition, batch) attached to datasets, following a schema defined for the project. |
| Sheet | A relational table in a project, with a typed schema and SQL queries. Apps can use sheets as a database; see Sheets. |
| Workspace | An interactive compute environment (such as a notebook server) with datasets mounted, which a user opens in the browser. |
| Share | A way to make datasets from one project available in another without copying them. |
| Reference | Reference data used by pipelines, such as genomes and annotations, stored in a project. |
| Notes and discussions | Comment threads attached to datasets, samples, workspaces and other objects. Apps should use notes to record what they did; see provenance by default. |
| Tags | Short text labels on projects, datasets, sheets and other objects, used for finding and organizing things. |
| App registration | A record of an app in a tenant: its callback URL (where it returns after sign-in), its client ID and the permissions it may use. A tenant admin creates it with discovery enabled, and the app gets its client ID from the tenant by its callback URL. A user with the App Developer role can register a localhost callback URL that works only for them, to develop the app before a tenant admin sets it up for others. The Cirro team registers apps on the public tenant. See app types and registration. |
- The user opens the app and is sent to Cirro's authorize page, which shows what the app is asking for; they sign in there with their Cirro account for one tenant.
- The app gets a token that acts as that user, limited to the permissions the tenant granted the app.
- The app calls the tenant's API with that token: listing projects, reading datasets, running pipelines, writing sheets.
- To read or write files, it asks the API for short-lived credentials and talks to storage directly.
Everything the app creates lands in the user's project, where other members see it in the Cirro web interface.
Next: getting started gets a template running against a real tenant.