As with all systems, Mosaic relies on files to store data. Files can be uploaded from your computer or generated by running apps, and can be shared with the Mosaic community.

Listing files

Clicking on "Files" at the top navigation bar takes you to the a page that lists all the files accessible by your account. Files owned by you are shown under "My Files" Members' contributions (including yours) are shown under "Explore". You can further filter files (for example, search for a given filename keyword) by clicking on the "eye" icon, which will reveal a filter bar. Choose any filters and apply them by clicking on the "funnel" icon.

Uploading files

You can upload small files directly from your web browser by clicking "Add files". Choose the files you want to upload, and click "Upload all" to begin the upload to cloud storage. To ensure integrity, your web browser will automatically calculate a checksum of the uploaded content and ensure that it matches the checksum calculated on the cloud side.

Once the upload is complete, the system will perform some additional finalization. This process usually takes a few seconds, during which the file is in a "closing" state. After finalization is completed, the file becomes "closed" and can now be used within Mosaic (downloaded, published, or provided as input in apps). Its contents can never be changed, and it is given a unique immutable id of the form "file-Bk0kjkQ0ZP01x1KJqQyqJ7yq" to distinguish it across the whole site.

If the upload gets interrupted for any reason, you will see the partially-uploaded file in your list of files, marked with an "open" state. Please delete the file and reupload it. Periodically, the Mosaic system may automatically clean up partially uploaded files.

TIP: Web browsers have limitations regarding the upload capabilities. Therefore, you should only use that method for small files. Read below for additional options if you have large data to upload.

For large files that are accessible over the Internet, we suggest running the "Fetch file from URL" app, which has been provided by the Mosaic team. The app allows you to fetch a file from a given URL.

For large files that are on your computer, we suggest using the Mosaic uploader, a command-line tool capable of uploading with multiple threads and more resilient to transient errors. The Mosaic uploader can be used for both files and app assets, and it's available through the Create Assets page.

Visit that page and download the Mosaic uploader by clicking the respective button under "Step 3".

The tool requires an "authorization key" in order to authenticate the client against the Mosaic system. You can get a key by clicking the respective button under "Step 4" in the "Add Assets" page. Copy the key from that page and paste it in the command below where it says KEY. For your security, the key is valid for 24h.

Run ./mosaic --cmd upload-file --key KEY --file /path/to/file --destination project-xxxx --skipverify true. This command will upload the file to Mosaic to a workspace with id "project-xxxx".

TIP: The uploader saves your key in $HOME/.config/mosaic/config.json, so after you have run it once, you don't need to specify the key in subsequent invocations.
Examining file origin

The system automatically records the origin of files. The "origin" column describes how each file got introduced to Mosaic; it is set to "Uploaded" if the file was directly uploaded; otherwise it points to a job if the file was generated by running an app. Further information can be obtained using the tracking feature.

File details

Clicking on a filename in the files list (or on other file links that appear in certain Mosaic areas) takes you to the file details page, which shows information such as filename, unique id, size, creation time, and origin.

This page shows one or more action buttons, depending on the file state and your permissions:

Click... In order to...
Attach to... Attach the file to a discussion. See the discussions section for more info.
Open Open the file inline in your browser (if your browser supports it). Use this action to see the content of text files, PDF files, images, etc.
Download Download the file right away via your browser.
Authorized URL Generate an authorized URL via which the file can be downloaded non-interactively.
Track Display a graph tracking the file's provenance. See Tracking for more info.
Publish Publicly contribute the file to the Mosaic community. See Publishing for more info.
Delete Permanently remove the file from Mosaic.

Files with the extension `biom` are treated specially on the mosaic platform. When you visit the detail page for these files you will get access to two visualization tabs, "Krona" and "Stacked Bar". By visiting these tabs for the first time, a process will launch to create the respective visualizations. Once these processes are complete, the charts will be available to view.