NANOTYPER

Telemetry information is collected by MinKNOW sequencing runs as per the Terms and Conditions to allow monitoring of experiment performance and provide support in troubleshooting cases. Some of this information is obtained from free-form text entry fields, therefore no personally identifiable information should be included. No sequence data is collected.

Please do not install updates automatically. You’ll be promted by email from our support team when the new update is ready for installation. To avoid unexpected issues with the new MinKNOW update, Omixon first validates the new software version and then informs customers.

The basic requirements for a GPU are

8GB GPU memory
CUDA Compute Capability >6.1
Nvidia Drivers which support a minimum CUDA version 11.1
Nvidia CUDA Toolkit v.11.x (Version 12 is NOT compatible)

Check the latest Site preparation guide or Instruction for use or contact us at support@omixon.com.

If the computer needs to be switched off and/or restarted it is always best to remove MinION and then proceed with the shutdown. This applies even in normal circumstances where the customer is finished with the computer and would like to shut it down.

If MinION was left in and you open MinKnow you may find some errors such as “no host found” or “cannot connect to host”. You might also see the message “please insert MinION to get started”. If you see any of these errors it is best to unplug and plug MinION back in. Give the software a moment and the device should register again on the Software Overview page.

In some cases when a MinION is plugged in or if MinION was left in while the computer was turned off/on again you might also see a MinION graphic/image on the Software Overview page with a “Connection error” message. If you see this you can unplug MinION and reconnect or, better, right-click the image and select the “Restart position” option. This will refresh the graphic and you should now see the normal MinION/flow cell image.

It is always best practice to restart the computer in between runs, whether this is shut down after a run or restarted/power-cycled before a new run is begun. Again in all cases, make sure MinION is not plugged in.

You can also Restart Position if you see the MinION image but it says there is no flow cell (and you have a flow cell inserted). You can either restart the position or physically take the flow cell out of MinION and put it back in again.

If there is a run error within the first few minutes of the sequencing run starting (“Run stopped with error”, “Run stopped due to internal error”), you can also Restart the position and set up the run again, or restart the computer entirely (remembering to unplug MinION first). The flow cell and library will not be affected. Ensure also the flow cell is inserted correctly into the device and ensure the device/USB cable is connected properly to the laptop. It is best also to ensure the USB cable is not being strained and that MinION is kept close to the computer – stretching of the cable can lead to disconnection.

During the setup of the run you can choose where you want to save the output files. Just click the magnifying glass symbol on the “Output location” box and select the destination folder.

Important note: MinKNOW stores raw signal files before they are converted into fast5 in the default partition where MinKNOW is installed. Ideally this has to be an internal SSD to avoid any data loss or corruption. This location is specified and can be changed in the minknow/conf/user_conf file however this would be at your own risk if the location is changed.

You can also change to a network drive through MinKNOW. On the “Output location” box select your network drive. This should work for both Windows and Ubuntu PCs.

In case this doesn’t work, the other alternative is to edit the user_conf file.

For Windows OS, you can access this file through C:\\Program Files\MinKnow\conf\user_conf. You need to change the value to the correct path to your network drive (if the path is wrong MinKNOW will error).
For Ubuntu systems, the user_conf is located in opt/ont/minknow/conf/user_conf. You can open it using a text editor (such as Notepad++) and you will need to edit the same value to the path of your network drive.

You should be aware that writing the output files directly to a network drive brings some risks. You will need a stable internet connection to do this. If the internet or network crashes or blips at all, this can lead to a run crash as MinKNOW will lose the output location. If that happens any raw/temporary data that MinKNOW is generating to move across to the network drive will be irretrievably lost. If you suffer an internet outage you will lose all of the raw data, resulting in no fast5 or fastq files generated at all. We always recommend customers write the data locally to “local drive://data” and then move the data off to a network drive etc. This allows for MinKNOW to dump the raw files to a folder locally if it suffers a run crash, which can be converted to fast5 and fastq files anytime. Internet blips or crashes will also not affect a run that is being written locally.

– If the computer needs to be switched off and/or restarted it is always best to remove the MinION and then proceed with the shut down. This applies even in normal circumstances where the customer is finished with the computer and would like to shut it down.
-It is always best to restart the computer in between runs, whether this is shut down after a run or restarted/power-cycled before a new run is begun. Again in all cases, make sure the MinION is not plugged in.
-If the MinION was left in and you open MinKNOW you may find some errors such as “no host found” or “cannot connect to host”. You might also see the message “please insert a MinION to get started”. If you see any of these errors it is best to unplug and replug the MinION in. Give the software a moment and the device should register again on the Software Overview page.
-In some cases when a MinION is plugged in or if a MinION was left in while the computer was turned off/on again you might also see a MinION graphic/image in the Software Overview page with a “Connection error” message. If you see this you can unplug the MinION and reattach or, better, right click the image and select the “Restart position” option. This will refresh the graphic and you should now see the normal MinION/flow cell image.
-You can also Restart Position if you see the MinION image but it says there is no flow cell (and you have a flow cell inserted). You can either restart the position or physically take the flow cell out of the MinION and put it back in again
-If there is a run error within the first few minutes of the sequencing run starting (“Run stopped with error”, “Run stopped due to internal error”), you can also Restart the position and set-up the run again, or restart the computer entirely (remembering to unplug the MinION first). The flow cell and library will not be affected. Ensure also the flow cell is inserted correctly into the device and ensure the device/usb cable is connected properly to the laptop. It is best also to ensure the usb cable is not being strained and that the MinION is kept close to the computer – stretching of the cable can lead to disconnection.

If sequencing errors persist or if you want to delve further into an error that was not resolved by any of above, you can find the logs for the device and send them to us or have your IT team take a look first. The logs can be found here:
/var/log/minknow/MNXXXXX

Most probably the basecalling option was not selected during the run set up. There could be however unexpected error that prevented to generate fastq files.

To recover your data, you can rerun the fastq file/s through the “Analysis” tab on MinKNOW to demultiplex it. Or you can rebasecall and demultiplex the fast5 files again through MinKNOW.

Another way of rebasecalling is to use the command line. Follow the instructions below:

Access guppy_basecaller through the Terminal (either on Linux or Windows). A general basecalling command looks something like this
$ guppy_basecaller -i -s -c dna_r9.4.1_450bps_hac.cfg –barcode_kits SQK-RBK110-96 –q_score 7 –trim_barcodes -x cuda:all

The would need to be a completed file path to the data you want to analyse e.g. /data/omixon_experiment/no_sample/Run_ID/fast5_pass, and likewise the -s would also need to be the path to where you want the data to be outputted to.

More information about guppy basecaller can be found here.

Check please the extension of the file. It must be written in small letters “.json”.

The unclassified folder within the fastq_pass folder is a group of fastq files that compose of reads which the software was unable to assign to a barcode. The potential cause of this could be that the barcode was either missing from the read as it was not attached during the library preparation, or that the barcode could not be properly read, potentially due to mutations in the barcode sequence (MinKnow should recognize a barcode as long as 60% of the sequence fits the expectation). It is normal to have an unclassified folder as there might always be some reads that cannot be assigned to a barcode due to above mentioned reasons.

The logs can be found here: /var/log/minknow/MNXXXXX

The recommended data output per sample is 110-140 Mb (megabases) in order to ensure optimal performance during the subsequent genotyping step.

Please note that NanoTYPER 2.x.x versions CAN handle multiple fastq files!

If the MinKNOW basecalling configuration is incorrect or the customer is using post-run basecalling, the MinKNOW generates several small FASTQ files instead of a single and large one.

If the NanoTYPER is not able able to handle those multiple FASTQ files for the same sample, we have to manually merge those files into a single one.

• First, launch the Ubuntu terminal or CMD in the folder where the FASTQ files are located or navigate until there;
• Then, make sure that the folder where the FASTQ files are located has writing permissions by executing the following command:

sudo chmod -w .

Note: the period at the end of the command above should be inserted as well.

• Then, merge the FASTQ files (this command can be performed either with the FASTQ file gz compressed [*.fastq.gz] or not [*.fastq]) using the following command (where the content within braces should be replaced):

Linux:

cat *.gz > fastq_runid_{long-run-id}_{barcode}_{unique-number}.fastq.gz

• A practical example for the replacement of the variables of the command above would be:

cat *.gz > fastq_runid_f2110fa627844e26356ca6059191c104539be713_barcode01_01.fastq.gz

Windows:

copy *.gz /b fastq_runid_{long-run-id}_{barcode}_{unique-number}.fastq.gz

• A practical example for the replacement of the variables of the command above would be:

copy *.gz /b fastq_runid_f2110fa627844e26356ca6059191c104539be713_barcode01_01.fastq.gz

Please do not forget to change the unique numbers (last variable of the string), to prevent Twin pairing the sample files that share the same!

Using “wildcards”:

Wildcard characters (like the asterisk – * )  can be used if needed for specific samples.

For example:

copy SU252*_*_*_L1_R1_001.fastq /b SU252_merged_L1_R1_001.fastq

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.

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.

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.

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.

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.

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.

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.