Mega-Task: Documentation for End Users and Comp Authors

[praeducer]

Sub-tasks

Higher Priority (like by end of 2022)

• [x] Start with using https://github.com/facebook/Docusaurus to dump into https://pages.github.com. Publish within the COINSTAC repo, not a separate repo. The pages become code as part of our existing workflow.
• [x] Bootcamp high level intro: What is COINSTAC? How is COINSTAC useful to my research (purpose)? Set vocabulary and general overview of features.
• [ ] Create diagrams and visuals to help understand all of the moving parts.
• [x] How to setup local environment on Windows
• [x] How to setup local environment on Linux
• [x] How to setup local environment on MacOS
• [ ] How to author a computation - specifically interfacing with the COINSTAC sim and API
• [ ] How to run standard TReNDS Center Docker containers in COINSTAC
• [ ] How to add my computation to an instance of COINSTAC - add to FAQ
• [ ] How to run a computation locally - add to FAQ
• [ ] Gather and merge all COINSTAC Inputs and Specs docs into one to rule them all: https://docs.google.com/document/d/1uEP6DBusdfD9TuZpgHst0rfdCGesEJkV9SZWsTlA1nU/edit#heading=h.hws9iwj7gv7e
• [ ] How to connect COINSTAC to a Vault and process it with a computation
• [ ] Highlight our core features and the computations that are best supported
• [ ] QA documentation for accuracy and completeness - @praeducer

Lower Priority (like early 2023)

• [ ] The steps for preparing data for a Vault
• [ ] A wiki page for each Vault so end users know how to use that data. Link from app to each Vault's wiki page.
• [ ] Security updates (see comment below): https://github.com/trendscenter/coinstac/blob/master/SECURITY.md
• [ ] How to create a Vault and put data in it - pre-processing local site data to package as a COINSTAC vault
• [ ] How to containerize a computation in Singularity
• [ ] How to run a distributed computation in the cloud
• [ ] How to run a computation on a GPU powered cluster
• [ ] How timeouts work

Related Tasks

https://github.com/trendscenter/coinstac/issues/1334

[praeducer]

Draft of "How to install COINSTAC GUI on Windows"

There was something small that I wanted to bring up as an addition to end user documentation .. presently we don't have any documentation for end users to download docker and setup coinstac .. we have links to coinstac release on GitHub but it would be good to have. A small section that lists here are two steps 1) docker 2) coinstac . And separated by operating system they have . Something like this :

For the following version of operating systems: Windows 11 64-bit: Home or Pro version 21H2 or higher, or Enterprise or Education version 21H2 or higher. Windows 10 64-bit: Home or Pro 21H1 (build 19043) or higher, or Enterprise or Education 20H2 (build 19042) or higher. Please follow the installation steps as here. https://docs.docker.com/desktop/install/windows-install/

If you have older versions like windows 7/8/10 Home: Download the docker file from here https://github.com/docker-archive/toolbox/releases/download/v19.03.1/DockerToolbox-19.03.1.exe

Once you download , follow the installation instructions as below until "To verify your current Docker version, run the following command" https://devconnected.com/how-to-install-docker-on-windows-7-8-10-home-and-pro/#1_Install_Docker_on_Windows_7810_Home

Once docker is running. Install COINSTAC latest version and make sure that you are able to login https://github.com/trendscenter/coinstac/releases/download/v6.5.0/COINSTAC-Setup-6.5.0.exe

That was written for windows user but similar can even applied for other OS’s. If we can include that sort of thing somewhere on GitHub , like if you can polish it and add other OS installation instructions . We can post that on GitHub and also on coinstac.org

Update

End users documentation: Supported windows OS: Windows 11 64-bit: Home or Pro version 21H2 or higher, or Enterprise or Education version 21H2 or higher. Windows 10 64-bit: Home or Pro 21H1 (build 19043) or higher, or Enterprise or Education 20H2 (build 19042) or higher. Please follow the installation steps as here. https://docs.docker.com/desktop/install/[windows-install/](https://docs.docker.com/desktop/install/windows-install/)

[hvgazula]

How about here? https://github.com/trendscenter/coinstac-first-example

[praeducer]

Thank you @hvgazula! I'll consider migrating that to the wiki and updating it for the recent changes to the system.

[praeducer]

Draft of: "How to prepare data for a Vault"

to vaultify the existing vaults (cobre FS, Cobre fMRI, CMI VBM, GICA vaults ) ..Typical process involves : checking data manually, gathering appropriate data from the source, cleaning, pre-processing, QC, gathering relevant covariates (demographics , cognitive measurements etc.) , vetting them on whats usable, getting an aggregated list with no missing values or fill missing values, getting enough data to make sure the relevant algorithm (ex: VBM regression) runs on the data (as in matrix singular error because columns are too similar etc., making sure we dont put too many correlated columns, may be this can be left on the end user not sure) , running the pipeline through COINSTAC (which usually involves testing the pipeline itself) on a hardware that can run it, interpret the results , feedback from Vince etc. /vetting process and making sure the data runs also with custom data and not just vault data by itself.

[praeducer]

Draft of: "How to install COINSTAC Linux?"

Install coinstac-simulator on centos 7: https://linuxize.com/post/how-to-install-node-js-on-centos-7/ sudo npm i -g coinstac-simulator

Install COINSTAC simulator and run an example code : https://github.com/trendscenter/coinstac-first-example

[praeducer]

@spanta28: I will take the lead on documentation for end users ( with Kelly , Javier and others) and documentation for comp authors( with brad , Javier and other comp authors ). Javier because he probably has inputs since he dealt with installing coinstac on end users computers and things related to comp UI integration. And everything else as it relates to core features ( testing all options , vetting input output data align with Vince , go to comp authors if changes need to be made , risk : Harsha not being available to help if changes needed )

[rssk]

https://github.com/trendscenter/coinstac/tree/master/algorithm-development

[spanta28]

Comp author documentation Plan Setup a 2 hour work session Dec 5(Monday) with Brad, Javier, Sunitha, Sandeep and potentially Harsh Setup another 2 hour work session Dec 8 as needed.

Update readme for single shot FS regression:

Update comments for scripts with doc strings Create new github repo if needed. Include a revised easy to understand summary of the following material in readme.

Brief overview of COINSTAC

https://coinstac.org/

https://github.com/trendscenter/coinstac

Some introductory Youtube demos Using COINSTAC https://www.youtube.com/watch?v=QL95M74usAA&list=PLwamoYspgQX4xpdUBwo-uy2k8IPq1ta7O&index=6

COINSTAC ENGIMA demo https://www.youtube.com/watch?v=flUSFwIPslU&list=PLwamoYspgQX4xpdUBwo-uy2k8IPq1ta7O&index=7

COINSTAC Vaults demo https://www.youtube.com/watch?v=Qw6QEwS-uXA&list=PLwamoYspgQX4xpdUBwo-uy2k8IPq1ta7O&index=8

How to contribute to computations

https://github.com/trendscenter/coinstac-first-example

https://github.com/trendscenter/coinstac/tree/master/algorithm-development

Create a compspec.json

Starting a Coinstac computatation begins with making a compspec.json a document that allows the Coinstac system to understand how to interact with your computation. This includes how the UI is generated, how computations can chain together, and input and output handling. A more in depth overview can be found here:

https://github.com/trendscenter/coinstac/blob/master/algorithm-development/coinstac-development-guide.md

Visualize how options in compspec.json looks in GUI:

https://trendscenter.github.io/coinstac-specgen/

A Docker Specification for NeuroImaging at TReNDs

Testing

Test all the options with simulator , vet the inputs and outputs to ensure computation is producing meaningful results

Test all the options with GUI , vet the inputs and outputs to ensure computation is producing meaningful results

Go to personnel

Sandeep Panta

Javier Romero

Brad Baker

Sunitha Basodi

Notes: Work off a docker template that Brad creates so that comp authors can inherit base image and add their scripts/software according to the specs.

@hvgazula more than welcome to join on the work sessions or review the material after the work sessions.

[hvgazula]

Yes, please send me the invite. Thanks.

[pixelsaurus]

Here's the inputspec / compspec documentation from before: https://docs.google.com/document/d/1uEP6DBusdfD9TuZpgHst0rfdCGesEJkV9SZWsTlA1nU/edit

Here's the helper tool: https://trendscenter.github.io/coinstac-specgen/

[praeducer]

Security Updates to Publish

Questions

1. Similarly, some sites view the Mosquitto protocol as being a security risk and do not allow it. Could you please provide more information that we can provide to the different IT institutes about this protocol and its use within coinstac?
2. How does coinstac handle parellization? If we need to run parallel processing at a single site (e.g. because of having a large dataset), is that principally operationalised by installing coinstac on a node with many cores, or is it managed by the application in some way? Do we need to manage parallelisation manually (e.g. by installing coinstac on multiple cluster nodes)?
3. We will need more information regarding security. The information you have provided already (https://github.com/trendscenter/coinstac/blob/master/SECURITY.md) is a good start, but for some sites, we need to make a case not only for the types of measure that are in place, but also the information that is transferred to show that we do not inadvertently ‘leak’ identifying information. Of course that is also dependent on the types of analysis we can run, but at least I think we will need to put an IT person in contact with someone from your side who can answer those kinds of questions.

Answers

1. MQTT is used (mosquitto is our broker server for MQTT), specifically with TLS, to communicate between nodes. MQTT is an alternative packet structure to HTTPS, and is mostly just a lightweight alternative that provides methods for subscriptions and retransmissions. However, if your institution blocks MQTT traffic, coinstac will fallback to tunneling MQTT traffic over websockets via HTTPS.
2. Parallelization would be entirely up to the computation (the singularity image) itself to manage which none of our current computations do but its a possibility. One alternative is running one site data as multiple sites, but in the context of cluster this could be complicated.
3. Sandeep - this sounds like a Anand Q?

[praeducer]

Basic intro to distributed learning (COINSTAC first example) CompSpec introduction InputSpec introduction Basic Docker File Principals (using Brad's template) Identifying where data comes from on Remote Continuous Data Regression with Iris Reading CSV data CSV to JSON translation Multiple Iterations Phase Keys for control flow Continued Docker Principals Multi-Shot Regression with FSL Covariate Data Structure Basic plot generation Writing Files to Disk Transferring Files between sites ... Advanced Concepts Cache Data Structure Advanced Docker Principals (What does that mean? - Brad) Tasks: Javier: Will do an initial rework of the Author Onboarding documentation Harsh: Will add documentation and basic refactoring to first example Brad (after Harsh): Will add logging to first example, and any additional refactoring as needed Brad (in parallel): Will review docker image in first example, and align with template efforts Sunitha (after Brad): Will also review first computation for clarity Sunitha (in parallel): Also will look for way to debug in PyCharm/VSCode Javier (after Harsh/Sunitha/Brad): Will harmonize first example and Onboarding documentation Next Meeting: 12/12/2022 - 11:30 AM EST

[spanta28]

@dylanmartin @rssk Here is a dump of the latest end user documentation for COINSTAC installation/run regression/Group ICA in the GUI.

I have taken the existing material on github created by Javier (https://github.com/trendscenter/coinstac-instructions/blob/master/coinstac-how-to-run-analysis.md) and added things to it and compiled this document. COINSTAC_installation_run_pipelines.docx This doc outlines steps for COINSTAC installation, running regression ( on FreeSurfer and VBM data using Vaults, sample data) and Spatially Constrained Group ICA.

I have compiled a privacy document from Anand's latest doc. COINSTAC_security_info.docx I have also added the existing security info. link (https://github.com/trendscenter/coinstac/blob/master/SECURITY.md) in this doc.

[spanta28]

@rssk @dylanmartin Here is the docx that I made for Gunter's group on privacy and end user documentation

[praeducer]

@pixelsaurus was kind of enough to run through setting up the COINSTAC client and running Ridge Regression Singleshot with me today. Here are my notes that I will incorporate into things like the Vault paper and our user documentation.

Vault user is like a virtual user. The data is a user. Then you don't have to wait on a human user. Vince likes Vaults so people can easily demo COINSTAC. Helps with adoption goals.

You'll need to install Docker and then grab the latest COINSTAC download: https://github.com/trendscenter/coinstac/releases Unpack COINSTAC-6.5.6-mac.zip then drag to application folder. Computations are GB large. Single digit GB at least. I increased resources in Docker (Swap RAM and file storage). Make sure we have min number dockers specs documented. You’ll want to grab the data from the test directory here: https://github.com/trendscenter/coinstac-ssr-fsl Before we run a computation we pull down data. Test inputs are for simulating sites. Like local0 is a separate site. They are each a dummy site. I'll do one data set and Javier will do another. paulprae@Pauls-MBP coinstac % git clone https://github.com/trendscenter/coinstac-ssr-fsl.git /Users/paulprae/workspace/coinstac/coinstac-ssr-fsl Consortia is a required first step before mapping data. Javier is acting as lead and setting up the pipeline. I am contributing a dataset. Javier is user OATS I joined SSR FSL consortia then mapped local data by clicking on the .csv file in local1. Pipeline owners sets up the covariates to the studying the pipeline. Checkmark indicates signed up to COINSTAC, joined consortia, and mapped data. Can see pipeline activity on Home Screen to confirm everything is running. Computation locations are managed in a central database.

Had to restart server if certain HTTP errors occur: ubuntu@coinstacprd01:~$ vi ./coinstac-restart.sh

!/bin/bash

set -e systemctl restart coinstac-api-server.service sleep 2 systemctl restart coinstac-server.service

Server has permissions to run computations on my laptop as soon as I map the data. COINSTAC client needs to be up in order for computations to be run.

[praeducer]

https://github.com/trendscenter/coinstac/tree/documentation/coinstac-docs @rssk and @dylanmartin Could we update these instructions so computation authors have enough information that they could easily contribute? I'm even having a hard time jumping in with this short description. Anand or I may add details around our federated learning / privacy approach. It feels like it assumes the reader knows how to build websites and use Docusaurus. We want anyone that can write documentation to be able to contribute easily, like researchers that use our platform.