The FAIRLYZ QC application runs in the user compute environment to protect the privacy of the data. The data is not uploaded to FAIRLYZ.com. Only metadata, summary statistics, and a QC score are synced with FAIRLYZ.
Review Previous Step
Complete the data profiling.
Installation
- Prerequisite: Docker needs to be installed (latest version) in a desktop environment, e.g. Windows, Mac. Open the Docker Application to make sure it is running.
- Open a terminal or command-line interface, in Windows, use PowerShell. You will install it from the command line. The command runs from the command line and must run in the same folder where all the files are present. Only those files can be used for QC. Use this sample data for testing if you don’t have data ready.
- Run the command :
docker run -v ${PWD}:/app/data -e HOST_PWD=${PWD} -p 8082:8082 -p 3000:3000 lifetimeomics/qc-app-web:0.9.8
- Monitor the command line and wait for a minute until the application has loaded. See the Troubleshooting Guide below if you get any errors such as PWD not being recognize in Windows Terminals.
- In FAIRLYZ, hit the “Refresh” button until the “Run QC” button becomes active. Click “Run QC” to switch to the FAIRLYZ QC application. Alternatively try this URL for QC of demographic data.
Warning
When running QC only select files that are used for the current study to ensure that the QC score is accurate and not polluted with outlier data. In the current version, when running QC on a different study, first navigate to the study and the specific data card in FAIRLYZ.com and open the App from there. When using files in a different directory, either copy them over, or delete the docker container, then the docker image, and rerun the command from the other directory.
Versions
To install a previous version of the app, add :version at the end of the docker run command.
| 0.9.8 | This is the latest version. It organizes the UI in sections and separates dictionary QC from mapping QC. It adds an addon to generate a data dictionary. It also provides an addon for OpenAI mapping of terms to annotate demographic and clinical data. It also improves UX design with more information and guidance in the UI. |
Next Step
Continue with the guide to Run FAIRLYZ QC.
Technical Guidance
Troubleshooting Guide
Windows Terminals ${PWD} Error
In some Windows Terminals ${PWD} will not work. In a terminal command line, PWD stands for Present Working Directory. It represents the current directory in which you are working. When you use the command echo ${PWD}, it will display the path to this directory. If it returns an error you will have to change the command to include your current directory in which you are working using the full path.
Solution
Change the command to include your current directory in which you are working using the full path. For example if you directory is
C:\Dev\Data\FAIRLYZ\dbGaP-sample-data
then run the command as:
docker run -v C:\Dev\Data\FAIRLYZ\dbGaP-sample-data:/app/data -e HOST_PWD=C:\Dev\Data\FAIRLYZ\dbGaP-sample-data -p 8082:8082 -p 3000:3000 lifetimeomics/qc-app-web
Docker Message: Unable to find image … 401 Unauthorized
The error indicates that Docker is unable to pull the specified image because it couldn’t authenticate successfully with Docker Hub. Even for public Docker images, certain circumstances can require authentication to Docker Hub.
Reasons Authentication May Be Required for Public Images:
Temporary Glitches: Sometimes, authentication is incorrectly required due to transient issues with Docker Hub.
Rate Limits for Anonymous Users: Docker Hub enforces rate limits on image pulls:
- Anonymous users (not logged in) are limited to 100 image pulls per 6 hours.
- Authenticated users have a higher limit (e.g., 200 image pulls per 6 hours).
If you’ve exceeded the anonymous pull limit, Docker will return a 401 Unauthorized error even for public images.
Solutions
- To rule out other errors, run:
docker pull hello-world
If that runs, then the error is not with your installation of docker but linked to this particular image. You will then either have to:
- Wait until you try to install again, or
- Log in to Docker Hub and then install it