Package: mhn
mhn: A Python package to efficiently compute Mutual Hazard NetworksMutual Hazard Networks (MHN) were first introduced bySchill et al. (2019)and are used to model cancer progression.This Python package can be used to work with MHNs. It includes functions that were part of the
original R implementation as well as functions that make use of state-space restriction
to make learning a new MHN from cancer data faster and more efficient. Furthermore, it
also contains functions to work with data for which the samples' ages are known and can
therefore be considered while learning an MHN (seeRupp et al. (2021)).There are optimizer classes for data with known sample ages as well as for data without, which make learning a new MHN possible with
only a few lines of code.DocumentationA detailed documentation of themhnpackage is availablehere.Install the mhn packageYou can install the mhn package using pip:pipinstallmhnAfter completing the installation of this package you should be able to import it by callingimportmhnIf a new version of the mhn package is available, you can upgrade your installation withpipinstall--upgrademhnA quick overviewThe package contains the original MHN functions implemented in Python. You import them frommhn.original:frommhn.originalimportLikelihood,ModelConstruction,RegularizedOptimization,UtilityFunctionsYou can train an MHN using state-space restriction. The corresponding functions
can be imported withfrommhn.ssrimportstate_space_restriction,state_containersThe functions that make use of the known ages of samples can be imported viafrommhn.ssrimportmatrix_exponentialUsing the CUDA implementation to accelerate score computationsIf your device has an Nvidia GPU, you can accelerate the computation of the log-likelihood score and its gradient for
both the full and the restricted state-space with CUDA.
For that you have to have CUDA and the CUDA compiler
installed on your device. You can check that in the terminal withnvcc--versionIf this command is recognized, then CUDA should be installed on your device.You can also use the following function to test if themhnpackage has access to
GPU-accelerated  functions:importmhnprint(mhn.cuda_available())# the three possible results are also available as constants:# CUDA_AVAILABLE, CUDA_NOT_AVAILABLE, CUDA_NOT_FUNCTIONALifmhn.cuda_available()==mhn.CUDA_AVAILABLE:print('CUDA is available')ifmhn.cuda_available()==mhn.CUDA_NOT_AVAILABLE:print('CUDA compiler nvcc was not present during installation')ifmhn.cuda_available()==mhn.CUDA_NOT_FUNCTIONAL:print('CUDA compiler nvcc available but CUDA functions not working. Check CUDA installation')Be especially aware of theCUDA_NOT_FUNCTIONALcase: This means that the CUDA compiler
is installed on your device but basic functionalities like allocating memory on the GPU
are not working as expected.
In this case something is probably wrong with your CUDA drivers and you should check your CUDA
installation.If you cannot resolveCUDA_NOT_FUNCTIONALby changing CUDA drivers, we recommend to install the package with CPU support only.
This can be accomplished on Linux viaexportINSTALL_MHN_NO_CUDA=1pipinstallmhnand on Windows viasetINSTALL_MHN_NO_CUDA=1pipinstallmhnIf you installednvccafter installing themhnpackage, you have to
reinstall this package to gain access to the CUDA functions.Reinstalling the package for CUDA-related reasonsIf you want to reinstall the package because you want to either
enable or disable CUDA support, you should add the--no-cache-dirflag during
installation to ensure thatpipdoes not use a cached version of the
package and that the package is actually recompiled:pipuninstallmhn
pipinstallmhn--no-cache-dirHow to train a new MHNThe simplest way to train a new MHN is to import theoptimizersmodule and
use theStateSpaceOptimizerclass.frommhn.optimizersimportStateSpaceOptimizeropt=StateSpaceOptimizer()We can specify the data that we want our MHN to be trained on:opt.load_data_matrix(data_matrix)Make sure, that the binary numpy matrixdata_matrixis set todtype=np.int32, else you
might get an error. Alternatively, if your training data is stored in a CSV file, you can callopt.load_data_from_csv(filename,delimiter)wheredelimiteris the delimiter separating the items in the CSV file (default:',').
Internally, this method uses pandas'read_csv()function to extract the data from the CSV file.
All additional keyword arguments given to this method will be passed on to that
pandas function. This means parameters likeusecolsorskiprowsof theread_csv()function can also be used as parameters for this method.If you want to make sure that the matrix was loaded correctly, you can get
the loaded matrix withloaded_matrix=opt.training_dataIf you work with a CUDA-capable device, you can choose which device you want to use to
train a new MHN:# uses both CPU and GPU depending on the number of mutations in the individual sampleopt.set_device(StateSpaceOptimizer.Device.AUTO)# use the CPU to compute log-likelihood score and gradientopt.set_device(StateSpaceOptimizer.Device.CPU)# use the GPU to compute log-likelihood score and gradientopt.set_device(StateSpaceOptimizer.Device.GPU)# you can also access the Device enum directly with an Optimizer objectopt.set_device(opt.Device.AUTO)You could also change the initial theta that is the starting point for training, which by default
is an independence model, withopt.set_init_theta(init_theta)If you want to regularly save the progress during training you can useopt.save_progress(steps=-1,always_new_file=False,filename='theta_backup.npy')The parameters of this method aresteps(default:-1): if positive, the number of iterations between two progress storagesalways_new_file(default:False): if True, creates a new file for every progress storage,
else the former progress file is overwritten each timefilename(default:"theta_backup.npy"): the file name of the progress file.Lastly, you could specify a callback function that is called after each training stepdefsome_callback_function(theta:np.ndarray):passopt.set_callback_func(some_callback_function)Finally, you can train a new MHN withfrommhn.optimizersimportStateSpaceOptimizeropt=StateSpaceOptimizer()opt=opt.load_data_from_csv(filename,delimiter)opt.train()Some important parameters of thetrainmethod includelam(default:0), which is
the lambda tuning parameter to control L1 regularization,maxit(default:5000), which is the maximum
number of training iterations,reltol(default:1e-7), which is the gradient norm at which the training terminates andround_result(default:True), which, if set to True, rounds the result to two decimal placesThe resulting MHN is returned by thetrain()method, but can also be obtained
from theresultparameter:new_mhn=opt.result