HOLOTYPE

In case you downloaded the installer to a Windows machine using Internet Explorer the file extension has most likely been removed from the executable due to security restrictions. This can be resolved by locating the file that you downloaded and renaming it to have the “.exe” extension. Simply add “.exe” to the end of the filename and it will be ready to run.

Prior to Twin 2.1.0 and Explore 1.3.0 Omixon HLA software installers came in bundles – this means that if you have a Desktop installation you will also have a Client available in the installation directory. You simply have to make sure that you start the omixon-hla-twin executable when you want to run the standalone application and use the client executable if you want to connect to a server.

If there are no firewalls between the server and your machine you should be able to connect without any specific configuration. Simply click “Add new server” and save the connection as is. Afterwards you can click “Connect” to connect to the server. In case there is a specific IP address or hostname configured for the server or if there is a firewall in between please refer to the Client-server configuration part of the FAQ.

This happens usually when you used a shortcut to startup the software. During installation it sometimes happens that the client shortcut that is created does not point to the actual client but to another executable available in the installation directory. The easiest way to resolve this is to navigate to the installation directory and startup the client executable manually. Once you verified that the software starts up as expected you can delete the faulty shortcut from your desktop and create a new one from the actual executable.

Startup the software and look at the title of the application in the top left part of the title bar. If you see “Omixon HLA Twin RUO” or “Omixon HLA Explore” – you are using the desktop application. If you see “Omixon HLA Twin RUO – using XYZ server” or something similar where the name of the server is included then you are using a client application connecting to a server.

Start the installer and on the first screen of the Setup Wizard you will be presented with two options – one of them is “Yes, update the existing installation”. In this case you have an existing installation that has been recognised by the installer and you can upgrade this installation by selecting this option and proceeding with the installation without modifying any folder names or paths during the installation. If you select the other option – “No, install into a different directory” – you can create a new, separate installation of the software by modifying the folder names or paths presented to you during installation. Please note that this latter method is not suitable to “move” an existing installation from one location to the other. It will create a new, separate installation without overwriting the previous one.

You will receive an Omixon license by email. You can right click on the link from which the license is available for download and use the “Save link as..” option to save the license to a suitable location. Please make sure that the license has a “.lic” extension and is not saved as a txt file. If it has been saved as a “txt” or as a “lic.txt” please rename it to have a “.lic” extension.

Start up the software and go to Application Settings. Use the “Display Hardware key” option available in the left hand “Administration” menu to display the hardware key. Since certain letters are indistinguishable based on a screenshot – for example “l” and “I” – we strongly recommend using the “Copy to clipboard” option available on the popup window which copies the hardware key to the clipboard from where you can easily paste it into an email.

Omixon HLA Twin and Explore use the machine id file, to generate a hardware key – a unique machine identifier for the Omixon application. The file must be accessible in /var/lib/dbus/machine-id, and it is a randomly generated by dbus-uuidgen, typically invoked by the post-install script of a D-Bus package. It can also be a symlink to /etc/machine-id, but the file has to be present in either way on the path above. In some Red-Hat distributions this path does not exist.
To fix it, run
$ dbus-uuidgen > /var/lib/dbus/machine-id
If you don’t have dbus-uuidgen , it’s in the dbus package, which can be installed by issuing
$ yum install dbus .

The most common cause of this problem is an outdated or missing video card driver. Twin and Explore require OpenGL 2.0 support from the video card to be displayed. If you want to use it on your own machine check if your video card supports this and if it does upgrade the driver and restart the application. If you are using Twin or Explore via Remote Desktop or X please note that these don’t forward the OpenGL support so while you can technically startup the application remotely – you will not be able to see it. To work around this – startup the application locally on the machine and then you can access and use it via Remote Desktop or X.

Another potential problem is when the application has been installed using a user account with administrator access and now you are trying to use it with a user account that does not have this privilege. Full access needs to be granted to the application folders which have been defined during installation – database folder, installation folder, and temp folder.

BitLocker on Windows can also prevent the application from running as it detects and prevents executables from running within a user profile. Configure BitLocker to allow this and the application will start up.

Since Twin 4.1.0, a running MySQL server is also required, without the MySQL server the Software can not start.

The user manual is located in the “doc” folder within the installation directory. The basics of setting up the configuration are detailed in the user manual so you can refer to that to get started.

There can be a number of issues preventing the connection – the two most common are different versions and firewalls. Please make sure that when you upgrade the server you upgrade all clients as well – to the same version. There are a number of ways to check the software versions – the first of them is to ensure that you used the installers with the same version number. If you don’t have the installers anymore you can check the client version number on the splash screen that pops up when you start the client. In case you don’t have a sufficient graphical display on the server, you can check the “server.log” of the server, located in the “logs” folder within the installation directory. Alternatively, feel free to send the logs to support@omixon.com for confirmation. When it comes to firewalls there are a number of test steps that can be executed to determine whether the firewall is preventing the connection – please see the “Client-server (TWIN 3.X.X AND EXPLORE 2.0.0) troubleshooting guide” for the detailed description.

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:
omixon-hla-server-executable status

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 by using your browser. For detailed instructions or 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.

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 deactivate a user, but the delete function is disabled.

• Users can only be deactivated/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.

HML is an abbreviation for Histoimmunogenetics Markup Language. It’s a standardized file format for storing and handling HLA and KIR genotyping results.

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.

You can easily compare the sequences of alleles in the Genome Browser using the “Masked reference” mode. This can be toggled using the “Toggle reference masked” function in the right click context menu or by pressing Ctrl + D (keep the cursor over the alignment while you do this).

Yes, base statistics is easily made visible by pressing F2 or choosing “Show base statistics at cursor” in the right click context menu.

Multiple alleles or allele pairs are called in case they have about equal amount of supporting reads (SG algorithm) or equal amount of mismatches (CG algorithm). This means that the software was not able to clearly decide which allele is present in the original biological sample. You can investigate and decide about the result or the necessary course of action based on the Genome Browser.

In case the reference sequence of the allele without mismatch is not fully defined and the other one is, then we use a method called “fair compare”. As we don’t know if the partially defined allele would have any mismatches if it was fully defined, we don’t discard the allele with the mismatch but show it as an ambiguous result.

The “Novel ref” sequence is the generated novel sequence while the “Rel ref” is the sequence of the selected base allele from the reference database. The novel allele is assumed to be derived from the base allele.

The QC traffic light system is meant to indicate the quality of the input data. The overall QC traffic light is calculated as the value of the worst QC measure of the given locus. The meaning of the different colours is the following:

• (green) – PASSED: the locus passed all QC tests
• (yellow/green) – INFO: one or more QC tests produced lower than average results
• (yellow) – INSPECT: one or more QC tests produced concerning results, manual inspection of the results needed
• (red/yellow) – INVESTIGATE: one or more QC tests showed low result quality, manual inspection and possibly reanalysis is needed
• (red) – FAILED: one or more QC tests showed very low result quality, manual inspection is needed to determine the cause and the locus or sample likely needs re-sequencing or to be re-typed by alternative methods

The first thing to do is when you see a QC metric warning or failure is to gain more information about the sample (read length, read quality, coverage, etc). Having more information makes it easier to diagnose the problem and make an informed decision about the required steps (e.g. full resequencing, resequencing from a specific step). Certain advanced analysis settings (e.g. processing more reads) can be used for compensating for some not too serious quality issues.

The CG genotyping algorithm was unable to build a consensus sequence to assign an allele to the given locus due to the low quality of the input data, but some of the QC metrics are calculated. Check the QC metrics to gain more information about the problems.

There are a few different reasons why this can happen.

• The result you opened was analysed with an older software version which didn’t have all the QC metrics that are currently present in the software
• The CG genotyping algorithm was unable to build a consensus sequence and consequently the QC measures calculated from the consensus couldn’t be calculated

You can add best matching genotype by navigating to the HLA Typing sample result screen and selecting “Add genotype” from the right click context menu. Browse the displayed P and G groups to locate the allele pair candidate that you wish to add. Please note that the already present result cannot be added again.

If you are in the Genome Browser you can add alleles by selecting “Add custom allele(s) to 1st/2nd chromosome” from the right click context menu. Note that if you choose this option then your selected alleles won’t be permanently attached to the sample. If you would like to convert the alleles that you added into a custom genotype please select “Convert custom allele pair to result genotype” from the right click context menu.

The manually added allele pair candidates can be removed by selecting them and using the right mouse button to summon the context menu. Select the “Delete user added genotype” option to remove the allele pair candidate.

You can see detailed information about a specific read by selecting it (left click) in the Genome Browser. The information will be visible in the bottom info bar. By selecting “Copy to clipboard” or “Copy sequence to clipboard” you can copy the desired information to the clipboard.