Merge pull request #311 from OpenImaging/documentaion-additions

Expand explanation in IMPORTING.md

IMPORTING.md

@@ -1,4 +1,17 @@
+## Objects in MIQA
+It may be helpful to know how objects are organized in MIQA before you start importing. Each user of MIQA may have a different way of storing their medical scans, so MIQA's object structure is intended to be flexible towards different organization methods.
+
+The top-level organization in MIQA is the Project. At the Project level, MIQA superusers may edit the import and export paths, perform imports and exports, and edit the users who have permissions on that project. Each project has a group of members who may be given read-only access, tier 1 review access, or tier 2 review access. To read more about User Roles in MIQA, see [USERS.md](USERS.md)
+
+Each Project has within it a set of Experiments, and each Experiment has within it a set of Scans. It is up to the superuser who creates this project how to organize image files in this schema. There is one final layer of organization that may be applied at the sub-Scan level: each Scan can have one or more Frames.
+
+Frames are intended to be any sub-scan structure, such as time-steps or positions. Sub-scan structures are not required but they are supported. If you have one image file per scan, then you should create one Frame object per Scan.
+In the case that you have multiple image files to associate with a single Scan, this is when multiple Frames can be made for a single Scan and when Frame ordering becomes applicable. Ordering can be applied to Frames in a Scan by their `frame_number`.
+
+
 ## Importing / Exporting Data
+Importing and exporting data to/from MIQA is a permission reserved for superusers, since these operations affect Project configuration.
+
 In MIQA, each Project has settings that allow you to specify file paths to an import file and an export file. The import file is how you ingest data into the project and the export file will write project contents into an ingestable format. These files must be either CSV or JSON. The file paths you specify should be absolute and visible to wherever your server is running.
 
 If you are using a production instance with native deployment, be sure that these paths are on the same machine and readable by the user that runs the Django server.
@@ -19,6 +32,25 @@ project_name, experiment_name, scan_name, scan_type, frame_number, file_location
 - Frame number: An integer to determine the order of Frames in a Scan. If only one Frame exists, enter 0 for this value.
 - File location: The file path of the image file (.nii.gz, .nii, .mgz, .nrrd). This can be an absolute path (with the same restrictions as above for the import file) or a relative path to the parent of the import file itself.
 
+Some examples follow.
+
+If you have two image files that belong to two separate scans, the CSV might look like:
+```
+project_name,experiment_name,scan_name,scan_type,frame_number,
+file_location
+My Project,My Experiment,Scan One,T1,0,/path/to/file1.nii.gz
+My Project,My Experiment,Scan Two,T1,0,/path/to/file2.nii.gz
+```
+
+But if you want to associate both image files with the same Scan, the CSV might look like:
+```
+project_name,experiment_name,scan_name,scan_type,frame_number,
+file_location
+My Project,My Experiment,My Scan,T1,0,/path/to/file1.nii.gz
+My Project,My Experiment,My Scan,T1,1,/path/to/file2.nii.gz
+```
+and in this case, both images would be reviewed as one scan.
+
 ### Import JSON
 If your import file is a JSON, the representation for Frames is nested into the representations for Scans within Experiments within your project. Below is an example of an import JSON:
 
@@ -64,4 +96,4 @@ The original Girder 3 MIQA server used a different CSV format with different col
 ```bash
 python dev/convert_miqa_import_csv_format.py old_import.csv another_import.csv
 ```
-This will create two new files `new_import.csv` and `new_another_import.csv` containing the same data in the new CSV format.
+This will create two new files `new_import.csv` and `new_another_import.csv` containing the same data in the new CSV format.

README.md

@@ -25,3 +25,5 @@ Get started right away using our pre-built docker containers.
 
 ### :page_with_curl: Documentation
 Read about configuring your instance of MIQA for production in [prod/README.md](prod/README.md) or for development in [dev/README.md](dev/README.md)
+
+Read about using MIQA's import feature in [IMPORTING.md](IMPORTING.md)

USERS.md

@@ -0,0 +1,27 @@
+## User Roles in MIQA
+MIQA users have a global role as well as any number of per-project roles.
+
+### Project Roles
+Each Project has a list of members specifying who may view and edit that project and the objects within.
+
+- Users added as "Collaborators" have read-only access. Collaborators cannot edit Experiment notes or submit decisions on scans.
+- Users added as "Members" have write access. Members can edit Experiment notes and submit decisions on scans. There are two classes of Members; A Member can either be "Tier 1 Reviewer" or "Tier 2 Reviewer".  Tier 1 Reviewers can submit a decision that a scan is either "usable" or "questionable". Tier 2 Reviewers can submit a decision that a scan is "usable", "unusable", or "usable-extra".
+
+A Scan is considered "unreviewed" when no decisions exist for that scan; it is not considered "complete" until a decision has been made by a Tier 2 Reviewer. If a Scan only has decisions made by Tier 1 Reviewers, it is considered as "needs Tier 2 review".
+
+**If a Project has no need to differentiate between reviewer tiers, simply set all reviewers as Tier 2.**
+
+> All Projects implicitly include _all superusers_ as Tier 1 Reviewers, since superusers automatically have edit permissions on every project. See below.
+
+### Global Roles
+Users can either be a superuser or a normal user with no heightened privileges. Superusers are trusted with the following privileges:
+
+- Can edit the import path and export path on projects
+- Can perform imports and exports on projects
+- Can delete projects
+- Can grant/revoke project roles to/from other users
+- Automatically have at least tier 1 reviewer privileges on every project
+- Can claim edit access on any Experiment (as long as the experiment is not currently being edited)
+- Can approve the accounts of new Users once the email for that new account has been confirmed
+
+**Normal Users will not be able to view or interact with a Project's settings (i.e. importing and exporting features).**