From a92c1d1036f01be4c920ebb1b849217ecc7037eb Mon Sep 17 00:00:00 2001 From: Dan Birman Date: Wed, 4 Dec 2024 09:22:11 -0800 Subject: [PATCH] docs: cleanup reference section --- README.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index a335df2..b2693cf 100644 --- a/README.md +++ b/README.md @@ -16,25 +16,29 @@ For AIND users, we expect your metrics to have actionable `value` fields. Either All metrics should have a `reference` figure attached. Even if you are just calculating numbers, your reference figures can put those numbers in context for viewers. -**Q: How do reference URLs get pulled into the QC Portal?** +**Q: How do references get pulled into the QC Portal?** -Each metric is associated with a reference figure. We support: +There are two aspects to refrences: (1) the type of the reference data, and (2) where the data is stored. These two aspects are independent. + +*Reference data types* - Vector files (svg, pdf) - Images (png, jpg, etc) - Interactive figures (e.g. altair) - Videos (mp4) -- Neuroglancer links (url) +- Embedded Neuroglancer and Figurl views (url, will be embedded in an *iframe*) - Rerun files (rrd - version number must be embedded in the filename in the format `filename_vX.Y.Z.rrd`) -Figures, images, and videos can be any size, but they will fit best on the screen if they are landscape and shaped roughly like a computer screen (for example, 640×480, 1280×800 or 1900×1200 px). +*Data storage* + +You have a few options for where to store files. In general we *prefer* that you store files in either the same data asset where the `quality_control.json` is located. The options below are in order of preference: -For images, figures, and videos, you can link to your references in several ways: +1. Provide the path to a file *relative to the `quality_control.json` file*, i.e. "figures/my_figure.png". Do not include the mount, asset name, or s3:// prefix. +2. Provide a kachery-cloud hash, i.e. "sha1://uuid.ext", note that you **must append the filetype**. The easiest way to do this is to set the `label` field to the filename, see below. +3. Provide a url to a publicly accessible file, i.e. "https://mywebsite.com/myfile.png" +4. Provide a path to any public S3 bucket, i.e. "s3://bucket/myfile.png" -- Provide a relative path to a file in the data asset's S3 bucket, i.e. "figures/my_figure.png". The mount/asset name should not be included. -- Provide a url to a publicly accessible file, i.e. "https://mywebsite.com/myfile.png" -- Provide a path to any public S3 bucket, i.e. "s3://bucket/myfile.png" -- Provide a kachery-cloud hash, i.e. "sha1://uuid.ext", note that you **must append the filetype**. The easiest way to do this is to set the `label` field to the filename, see below. +Neuroglancer and Figurl links should point to the exact URL that opens the view you want. **Q: I saw fancy things like dropdowns in the QC Portal, how do I do that?**