/>

Common Troubleshooting

 

Troubleshooting

General
Accounts
Uploading files
Panels
Gating
Slow performance
Algorithm failures

FlowSOM
CITRUS
SPADE
viSNE

General

  • What should I do if I need more help?

For help with anything about your Cytobank account or usage, submit a support ticket at the support site support.cytobank.org by following the link here. Please be as specific as possible about your question. Pro tip: If you think you will want us to look at your specific experiment, share it with us by clicking “Sharing” at the top right corner of your experiment and search for “Cytobank Support.” In your email, send us the link to your experiment and we’ll be able to get started solving your problem sooner.

Accounts 

  • I don’t see a verification email after registering for a Cytobank account. What should I do? 

Check your spam folder. If it is not there, contact support by submitting a support ticket at support.cytobank.org

Uploading files

Make sure you have a fast, stable internet connection. At least 50 Mbps download speed is recommended. You can check your speed at  http://www.speedtest.net/

If uploading large files, (for example, over 2 million events per file) or more than 50 files, try to upload in small batches, a few files at a time.

If you see an error in processing files after upload, clear your browser cache, and retry. If it still does not work, retry in a new experiment. 

  • What should I do if there are errors/warnings in my FCS file summaries?

Errors/warnings appear as a result of Cytobank’s quality control checks of FCS keywords during file upload, as described here. Some can be problematic while others will not impact your analysis. You can re-write your FCS files within Cytobank to try to generate new files with all the required FCS keywords.

  • What should I do if my ACS upload fails?

Exported .acs files contain all FCS files, attachments, illustrations, and advanced analyses (if that option is selected) associated with your experiment, so they are very large. As is the case for any large file upload/download, make sure you have a fast, stable internet connection. If the upload fails, clear your browser’s cache and try again a couple of times.  Pro tip: If it still fails, change the .acs file extension to .zip. Unzip the file, and you will have access to the original experiment FCS files, the gatingML. If you exported .acs with advanced analyses, each advanced analysis experiment will be in its own .acs file in a separate folder. Please upload individual .acs files separately.  

Panels

  • My files are assigned to different panels, but I want them in the same panel for my analysis. What should I do?

See options here for fixing mismatched panels in your experiment. Pro tip: Spare yourself from this problem by always acquiring any data you want to analyze together with the same template, ensuring the same channel names every single time.

Gating

  • Why are my gates hidden (H)?

Here is an explanation of why your gates say (H) and how to fix it. Pro tip: Take a few minutes before starting any gating or analysis in your experiment to review your scales settings thoroughly to prevent problems with hidden gates later on.

Why is Cytobank working slowly and what should I do?

  •  Slow file uploads

Make sure you have a fast, stable internet connection. At least 50 Mbps download speed is recommended. You can check your speed at  http://www.speedtest.net/.

  • Slow plots loading in illustration or gating

Ensure you have a fast, stable internet connection (see above).

Currently, having very large FCS files, or a high number of FCS files or channels in your experiment may slow down working in your experiment. In this case, you may improve performance by using the Split Files by Population feature to export populations of interest into a new experiment.

If you have an illustration with many plots loading slowly, try to refresh your browser a few times while plots load. Plots should load incrementally until the entire illustration is complete.

  • Advanced analysis task is stuck in the queue 

Please refer to Why is my experiment “in queue”? in the FAQs
If none of the above steps help, let us know what’s going on by submitting a support ticket via our support site

Algorithm failures

General 

There are a few common reasons that algorithms tend to fail:

Files are too large, which can be from a combination of the number of files, events, and/or channels. Try reducing file size by using Split Files by Population down to the population of interest.

FCS files were not written with the standard keywords. This happens more commonly with data generated from some instruments/acquisition software. This can often be remedied by re-writing your FCS files.

If neither of the above works, please contact support by submitting a support ticket via our support site 

FlowSOM

  • Why did my FlowSOM analysis fail?

FlowSOM is a very powerful and fast clustering tool. With FlowSOM in Cytobank, you can include up to 4 million events on Premium and 8 million events by default on Enterprise with the possibilities to customize the max limit. Please write into Cytobank Support for more information. Certain combinations of large numbers of events plus large numbers of total channels in your files (not just selected channels) can cause FlowSOM runs to fail even if the total number of events is under the max cap. If you see a warning message about “data approaching memory limits” in the Event Sampling box prior to starting a FlowSOM run, it means that your run may fail due to its large size. You can adjust the total number of events that will be included in your FlowSOM run in the 'Event Sampling' box on the setup page. Please refer to the FlowSOM setup article for more details. 

  • There are too many channels in my FlowSOM star charts to discern the channel expression

The channels in the star charts are the same as the clustering channels you selected. Currently, there is no option available to select specific channels to be included in the star charts. Please write to us to request this feature to be added for a future release. 

CITRUS

  • Why did my CITRUS analysis fail?

A CITRUS analysis may fail for many reasons. To help us quickly identify the cause of your problem, please contact the Cytobank support team at and share your experiment with “Cytobank Support”. After sharing the experiment, please email us the link to the shared experiment. 

  • CITRUS settings page is stuck fetching event counts

You may see this error because there are too many events in your samples. To fix this problem, you can create clean-up gates to identify doublets and non-cell events and then run “Split Files By Population” in Cytobank to reduce the size of your sample data files by removing unwanted events. In addition to removing unwanted events, you can use the “Split Files By Population” to reduce the size of input files. For example, you can identify the CD4+ T cell population and run CITRUS with only CD4+ T cells. 

  • What does it mean if my Model Error Rate plot looks bad and what should I do?

You can get the model error rate plot if you run the PAM and LASSO methods. The model error rate of your CITRUS run may be high because 1) your data has an unbalanced experimental design or 2) the clustering step in CITRUS fails to identify the right cell clusters that are significantly correlated with the status of sample conditions.

The unbalanced experimental design means that one of the sample groups has many more samples than the other sample group. One possible solution to this problem is to balance the sample size between groups. For example, you can reduce the number of samples in the group that has many samples to match the sample size of the other groups. 

To improve the model error rate for case #2, you may want to change clustering settings to create more cell clusters because this large set of clusters may contain the true significant clusters/biomarkers that you can find with a small set of clusters. 

  • Why do I have no significant clusters in my CITRUS results?

CITRUS may not identify any significant clusters because 1) the significant FDR cutoff used in SAM is too low. You should increase the cutoff value to let more clusters pass the cutoff or 2) the data doesn’t contain any cell clusters that can be strong predictors to predict the condition of input samples. You may want to double-check what channels you selected for the CITRUS analysis and make sure the selected channels can allow the clustering algorithm to identify biologically meaningful clusters.

 SPADE

  • Why did my SPADE analysis fail? 

There are many possible reasons a SPADE analysis could fail. A common cause of failure we see is that the FCS file keywords. Sometimes, but not always, problematic FCS files will give warnings in the FCS File Summary page. To use these problematic FCS files, try to re-write the FCS files in Cytobank. If that still does not work, export events (including compensation) as TEXT, and upload via DROP.

viSNE

  • Why did my viSNE analysis fail?

 Please check the most common issues listed below for troubleshooting. 

The most common issue for viSNE to fail is memory. Some things you can try to achieve success include: rerunning the viSNE with a lower perplexity and/or lower iterations or changing theta to 0.8. When you are running viSNE on or close to the max event cap with a large panel, even though it allows you to start the run, it may still fail during the process. Please see the advice below for solutions to reduce the experiment size by pre-gating and “Split Files By Population” to reduce the size of input files

If this is related to FCS format? Some instruments have large dynamic ranges. For example, Biorad ZE5 Yeti data writes FCS files in the range of 10^5 to 10^9, generating random distribution viSNE map. Biorad offers the option to export the FCS files for 3rd party option. With that export, the data range is more standard and will be appropriately formatted for viSNE. Please write into Cytobank Support if you are not sure of the compatibility. 

If this is related to scaling? Make sure your scales are all in Arcsinh, not log scale. Having scales set in log scale will block the viSNE run. 

  • viSNE settings page is stuck fetching event counts

You may see this error because there are too many events in your samples. To fix this problem, you can create clean-up gates to identify doublets and non-cell events and then run “Split Files By Population” in Cytobank to reduce the size of your sample data files by removing unwanted events. In addition to remove unwanted events, you can use the “Split Files By Population” to reduce the size of input files. For example, you can identify the CD4+ T cell population and run viSNE with only CD4+ T cells. 

 There may be multiple panels within the experiment. viSNE will only run on common channels among all the panels. Sometimes fetching data page will get stuck when there are multiple panels in the experiment. You will need to resolve the panel/channel issues before the viSNE run. 

  • viSNE islands are poorly separated

See this explanation on how to assess the quality of your viSNE map and adjust settings if the islands are not clearly resolved.

Poor resolution can result from data that are not adequately prepared. Make sure that your compensation, scaling, and pre-gating have been performed. In particular, viSNE needs data to be scaled by the same transformation, so ensure that you are not selecting fluorescence channels transformed by arcsinh, and scatter channels in linear, for example.



Have more questions? Submit a request