General Software Usage
Client-server connectivity troubleshooting guide
Starting the Software
There are multiple different issues that can lead to this. Please check the following:
- Both the folder specified during installation for the database and the specified temp folder are writable.
- The software is runnable by the current user (e.g. not only by a root/admin user).
- The log files do not contain any errors or exceptions.
- If there are errors or exceptions in the log file or you can’t find any obvious reason for the issue, please contact the support team.
Prior to Twin 2.1.0 and Explore 1.3.0 Omixon HLA software installers came in bundles. The desktop version of the software contained both a client executable and a desktop executable. If you have a desktop version, make sure that you have used the correct executable (e.g. omixon-hla-twin instead of omixon-hla-twin-client).
If you cannot connect to an already configured server, please check the status of the server first. You can do this using the following command:
If the server is not running, please start the server and try connecting again.
If the server is running please check the next section.For newly installed servers, the most common issue is misconfiguration. If you cannot connect to your server, please check the following things:
- In the client’s connection configuration, ‘Server host’ must be set the exact same value as ‘-Domixon.server.host’ in the server configuration file.
- Make sure that the server hostname resolves to the same IP on the server and client machines otherwise the clients will get a connection refused error. It is a common configuration problem that the hostname resolves to a different IP on the server (e.g. to 127.0.0.1 via an internal network interface) which causes connection deny.
- It is always safe to specify an exact IP address both for the server and clients which is reachable from all the related machines across the network.
Verify that the set port and the next one are both free for use on the server and client machines.
- If no issues were found using the checks above, please contact your system administrator and ask for firewall settings that can interfere with the connection.
You can reset your password using the password reset tool provided with the application. For a detailed description, check the “Password reset” section of the user manual. If you forgot your username, please contact the Omixon support team.
With the software, a default IMGT/HLA database (currently IMGT/HLA database version 3.24.0) is provided. Some extended allele sequences that have been published in peer-reviewed journals, but as of yet not part of the IMGT/HLA database can also be used by the Omixon softwares. You can enable or disable the usage of this extended database at the first startup and modify this setting at any time on the Settings dashboard.
Extended allele sequences resolve some common ambiguities, therefore the usage of the extended database is recommended.
- When will my license expire?
You can check the expiration date of your license on the Settings dashboard.
- Can I use a single license on multiple computers?
No, licenses contain a hardware key of the specific machine they were created for. If you want to use the software on a different machine, please contact the Omixon support team.
- Can I use a single shared license on a computing cluster?
This option is currently not available, but more advanced license handling is planned for the near future.
Software info Setup and Configurations
Both the exact software version and edition are available on the Settings dashboard. Note, that in the tooltip that is shown when the mouse pointer is over an analysis on the HLA Typing dashboard and in the header of the HLA Typing sample result screen, the software and IMGT/HLA database version used for analysing the current analysis are shown, not the current software or active database versions.
- Which database is active?
The active database is always shown in the header of the HLA Typing dashboard.
- I want to use a different version of the IMGT/HLA database. How can I install it in the software?
Different IMGT/HLA database versions can be installed using the Install HLA database wizard on the settings dashboard. Note, that not all database versions are available, only those which were validated by the Omixon team. If you have to use a specific, unavailable IMGT/HLA database version for some reason, please contact the Omixon support team.
- I installed a new IMGT/HLA database, but the software still uses the old one.
In all cases, the active database version is used for testing. You can set the active database in the Select active HLA database wizard on the Settings dashboard. Note, that when a new database version is installed, it is not automatically selected as the active database.
- I need a different IMGT/HLA database version but my computer do not have internet access or I’ve tried to download the file, but the task failed.
Download links for all available IMGT/HLA database versions are available in the built-in help of the Install HLA database wizard and also in the similar section of the user manual. If the database cannot be downloaded from within the software for some reason, please download the required database zip archive using the provided link, copy it to your local file system (or any drive visible by the software) and import it using the Select local file option of the database installation wizard.
- I want to enable or disable database extensions.
Database extensions can be configured at any time on the Settings dashboard. Note, that extended allele sequences are only available from version 3.24.0 of the IMGT/HLA database or higher.
- The software runs very slowly.
Check if your computer matches the minimum hardware requirements for the software. If not, please consider upgrading your hardware or using the client-server version of the software.
- If your computer has available memory, you can allocate more memory to the software. You can do this in the Memory settings wizard on the Settings dashboard. On average the best setup is somewhere between 2/3 and 3/4 of the total physical memory, e.g. 12G for a machine with 16G RAM. Note, that the application has to be restarted before to allow the new memory settings to come into effect. Memory settings for the server can be set via the same wizard in a client connected to the server. Memory settings for all software instances can also be set in the omixon-hla-executable.vmoptions files.
What’s the difference between a superuser and an analyst user?
- The first user created when a freshly installed application is started automatically becomes a superuser.
- A superuser is authorised to use all functions in the application. On top of the analyst role’s permissions the superuser can also use Administrative functions, run Advanced HLA typing, Import function and Create/Save Protocol.
- Analyst users can perform all standard activities related to sample analysis including Holotype HLA typing, View/Use Protocol and Export functions.
I want to delete a user, but the delete function is disabled.
- Users can only be deleted/edited/created by a superuser.
- After the first startup there must at least one superuser registered in the application at all times. If you have a single superuser account and want to delete it, please register a new superuser account first.
Default visualization settings for the current user can be changed using the following wizards available from the Settings dashboard:
- Genome browser setup (e.g. default browser orientation or base colours can be set),
- HLA result display (e.g. result status based filtering can be set).
- For HLA genotyping, a progress bar is showed next to every sample that are currently under analysis or are waiting for analysis.
- For all tasks, the overall progress of the scheduled task is shown in the top right notification box of the task manager. Progress and status of single tasks can be monitored using the task manager wizard which can be opened by clicking the same status box.
- If only one task (e.g. HLA typing) is running you check the task progress in either the task progress status box in the top right corner of the application.
- For multi-sample genotyping runs, the progress for a single sample can be checked on the sample level progress bar showed next to every sample that is scheduled for analysis.
All tasks can be aborted in the task manager. Genotyping tasks can also be aborted by pressing the red X icon next to the sample that is being analysed or waiting for analysis. Note, that for batch analysis tasks, pressing the sample level abort icon will abort analysis for all samples in the multi-sample analysis.
You can select any number of samples (or select all samples in the current folder by clicking CTRL+A) and use either the default or the advanced typing wizard to start an analysis for all the selected samples.
- Check the status of the Show Samples and Show Analyses buttons.
- Check the file filter function.
- Check that the required files are available in the folder in your operating system’s file browser. Check file permissions.
- Check file extensions. For fastq files fastq or fastq.gz file extensions are expected, while for HLA typing result a htr extension is required.
This can happen due to multiple different reasons:
- There are read files in the current folder, but no sample is selected. In this case, please select one or more samples.
- There are no read files in the current folder. In this case, please navigate to a folder that contains NGS data in one of the required formats (i.e. fastq or fastq.gz) and select a sample (or multiple samples).
- Your license has expired. You can check the expiration date of your license on the Settings dashboard.
- First check the both short reads files are present in the folder and both files are readable. If both are true, please check the next section.
- Read files are paired based on the Illumina naming conventions. If a non-default filename convention is used or there are multiple file pairs that match the same pattern, a fallback pairing method is initiated. This method assumes that filenames within a pair differ in a single character (e.g. sample1_1.fastq,gz and sample_1_2.fastq.gz). If file pairing is not successful, both files in a pair will show up as single data. In this case, please rename the relevant files.
Due to the low coverage and large data size, the Explore edition of the software is strongly suggested for non-targeted datasets. A usual workflow for big data analysis should include Filtering as a starting step. The resulting small read files only contain reads that map to any of the alleles in the IMGT/HLA database and can be analysed and re-analysed significantly faster than the original, unfiltered read files. For HLA genotyping of whole genome or whole exome data, the following settings should be used: all loci has to be selected as targeted in the Configure HLA targeted genes wizard, all reads should be processed and quality based subsampling should be turned off (the latter two parameters can be set in the Advanced HLA Typing wizard).
- WGS and WXS data is identified based on file sizes. If your input data files are unusually small and is not recognized as non-targeted data, please use the default genotyping options instead.
- You don’t have a license for the Big data module. You can check your installed licenses on the Settings dashboard.
This can happen if your read data does not fit the default Holotype protocol. E.g. you have single end or flowspace data while the Holotype protocol uses paired Illumina data.
- The most important run parameters are shown in a tooltip which appears when you hover the mouse over the name of the analysis on the HLA typing dashboard.
- All analysis details can be reviewed by selecting a single analysis and clicking Show protocol in the right-click menu.
- Both application and IMGT/HLA database versions can be seen in a tooltip when the mouse is over the name of the analysis result on the HLA Typing dashboard.
- The same version information for the currently viewed analysis result is also available in the header of the HLA Typing sample result screen.
If a task fails details can be checked on the Error details tab of the Task properties screen. The same error message can also be checked in the relevant log file.
There are several common issues, the most common categories are the following:
- Memory related issues (e.g. “OutOfMemoryError”, “GC overhead limit exceeded”). In this case, please check the memory settings and hardware requirements of the software.
- Input data related issues (e.g. “unexpected end of zlib input stream”). In this case, please check the integrity of your read files (e.g. try to unpack the files or check the number of lines in both fastq files).
HML is an abbreviation for Histoimmunogenetics Markup Language. It’s a standardized file format for storing and handling HLA and KIR genotyping results.
The generic metadata file can be created manually using an example file. Sample metadata files can be generated using a script provided separately. Please contact the Omixon support team for further details!
Consensus sequences for a locus can be exported from the HLA browser. The same sequences are also available from results exported in the standard HML format.