adabmDCA documentation

This tutorial presents a new version of adabmDCA [Muntoni et al., 2021]. The package comes in three different languages: C++ (single-core CPU), Julia (multi-core CPU), and Python (GPU-oriented). They share the same front-end interface from the terminal allowing the user to install and use one of the three equivalent versions based on hardware or software constraints.

We provide three different training routines:

• bmDCA: Trains a fully-connected DCA model [Figliuzzi et al., 2018];

• eaDCA: Trains a DCA model on a sparse coupling network by progressively adding couplings during the training [Calvanese et al., 2024];

• edDCA: Starts from a trained bmDCA model and iteratively removes the less informative couplings until the target sparsity is reached [Barrat-Charlaix et al., 2021].

Additionally, we provide several routines for sampling and analyzing the generated sequences once a DCA model is trained, for constructing and evaluating - according to a DCA model - a single mutant library from a given wild type, and finally, for computing the pairwise contact scores, in terms of average-product corrected Frobenius norms of the DCA couplings [Ekeberg et al., 2013].

If you want to directly jump to the command-line interface for using the package, go to the section Quicklist.

The main Github repository of the project can be found at adabmDCA 2.0.

Contents:

• Installation
  • Python implementation
    • Option 1: Install from PyPI
    • Option 2: Install from the GitHub repository
  • Julia implementation
    • Option 1: Using bash command
    • Option 2: Manual Installation via Julia
  • C++ implementation
• Input data and preprocessing
  • Input data
  • Preprocessing
    • Preprocessing pipeline
    • Computing the importance weights
    • Pseudo count and reweighted statistics
• Implementation
  • Output files
  • Restoring an interrupted training
  • Importance weights
  • Choosing the alphabet
  • eaDCA
  • edDCA
  • How to choose the hyperparameters?
    • Learning rate
    • Number of Markov Chains
    • Number of Monte Carlo steps
    • Regularization
• Applications
  • Generate sequences
    • Convergence criterium
  • Contact prediction
  • Scoring a sequence set
  • Single mutant library
• Boltzmann learning of biological models
  • Structure of the model and Boltzmann learning
    • Training the model
    • Monte Carlo estimation of the gradient
    • Convergence criterium
  • Training sparse models
    • Element activation DCA
    • Element decimation DCA
    • Parameter updates in between decimations/activations
• Quicklist
• Script Arguments
  • Train a DCA model
  • Sampling from a DCA model
  • Computing DCA energies of a MSA
  • Generate a Deep Mutational Scan (DMS) from a wild type
  • Compute the Frobenius contact matrix
• adabmDCApy APIs
  • Submodules
    • adabmDCA.dataset module
      • DatasetDCA
    • adabmDCA.fasta_utils module
      • compute_weights()
      • decode_sequence()
      • encode_sequence()
      • get_tokens()
      • import_clean_dataset()
      • import_from_fasta()
      • validate_alphabet()
      • write_fasta()
    • adabmDCA.functional module
      • one_hot()
    • adabmDCA.graph module
      • decimate_graph()
      • update_mask()
    • adabmDCA.io module
      • load_chains()
      • load_params()
      • load_params_oldformat()
      • save_chains()
      • save_params()
      • save_params_oldformat()
    • adabmDCA.parser module
      • add_args_contacts()
      • add_args_dca()
      • add_args_dms()
      • add_args_eaDCA()
      • add_args_edDCA()
      • add_args_energies()
      • add_args_sample()
      • add_args_train()
    • adabmDCA.plot module
      • plot_PCA()
      • plot_autocorrelation()
      • plot_hist()
      • plot_pearson_sampling()
      • plot_scatter_correlations()
      • plot_scatter_labels()
    • adabmDCA.resampling module
      • compute_mixing_time()
    • adabmDCA.sampling module
      • get_deltaE()
      • get_sampler()
      • gibbs_sampling()
      • metropolis()
      • metropolis_sweep()
    • adabmDCA.statmech module
      • compute_energy()
      • compute_entropy()
      • compute_logZ_exact()
      • compute_log_likelihood()
      • enumerate_states()
      • update_weights_AIS()
    • adabmDCA.stats module
      • extract_Cij_from_freq()
      • extract_Cij_from_seqs()
      • generate_unique_triplets()
      • get_correlation_two_points()
      • get_covariance_matrix()
      • get_freq_single_point()
      • get_freq_three_points()
      • get_freq_two_points()
      • get_slope()
    • adabmDCA.training module
      • train_graph()
      • update()
    • adabmDCA.utils module
      • get_device()
      • get_mask_save()
      • init_chains()
      • init_parameters()
      • resample_sequences()
      • set_zerosum_gauge()
    • Module contents
• References