MASSA-Algorithm 0.9.1__tar.gz → 1.0.0__tar.gz

massa_algorithm-1.0.0/MASSA_Algorithm/MASSA.py

@@ -0,0 +1,286 @@
+from MASSA_Algorithm import MASSAlogos
+from MASSA_Algorithm import MASSAargs
+from MASSA_Algorithm import MASSAod
+from MASSA_Algorithm import MASSAopen_files
+from MASSA_Algorithm import MASSAextraction
+from MASSA_Algorithm import MASSAdescriptors
+from MASSA_Algorithm import MASSApreparation
+from MASSA_Algorithm import MASSAcluster
+from MASSA_Algorithm import MASSAsplit
+from MASSA_Algorithm import MASSAmoloutput
+
+
+def returns_zero(total, test, validation):
+    """
+    Description:
+        It evaluates whether the distribution is inadequate. That is,
+        when the iterated cluster has a percentage greater than 0.5%
+        in the complete dataset but less than 0.5% in the test set.
+
+    Args:
+        total (dict):
+        Percentage of molecules in each cluster for the whole dataset.
+
+        test (dict):
+        Percentage of molecules in each cluster for the test subset.
+
+        validation (dict):
+        Percentage of molecules in each cluster for the validation subset.
+
+    Returns:
+        definer (boolean): Returns True if the distribution is
+                           inadequate, and False if it is adequate.
+    """
+    definer = False
+    for i in total.keys():
+        if (total[i] > 0.5) and (test[i] <= 0.5):
+            # Definer = True (Distribution was not done properly).
+            definer = True
+        elif validation != None:
+            if (total[i] > 0.5) and (validation[i] <= 0.5):
+                definer = True
+    return definer
+
+
+def main():
+    """
+    Description:
+        Main subroutine, allows the program to run directly from
+        the command line when installed via pip.
+    """
+    # Initializing from the command line.
+    # Print the program logo:
+    MASSAlogos.initial_print()
+
+    # It captures command line arguments.
+    (file_input,
+     file_output,
+     directoryfile_output,
+     extension_type,
+     dendrogram_xfont_size,
+     barplot_xfont_size,
+     training_percent,
+     number_bioact,
+     bioactivities_as_args,
+     npcs,
+     svd_parameter,
+     linkage_method,
+     flag_dendrogram,
+     splitting_strategy,
+     drop_errors) = MASSAargs.capture_args()
+    print('Initializing, wait...\n')
+
+    # Create log.txt file in directory:
+    arqlog = directoryfile_output+'/log.txt'
+    writelog = open(arqlog, 'w')
+
+    # Initial file management:
+    # It creates the output directories.
+    MASSAod.output_directory(directoryfile_output)
+    # Read molecules.
+    mols = MASSAopen_files.read_molecules(file_input, writelog, drop_errors)
+    # Extracting the property names from the ".sdf" input file.
+    sdf_property_names = MASSAopen_files.get_sdf_property_names(mols)
+    # Structure 3D management - It adds hydrogens keeping 3D coordenates.
+    mols_h = MASSAopen_files.hydrogen_add(mols)
+
+    # Extraction properties from ".sdf":
+    # It extracts the names of the molecules and creates a name:molecule dictionary and a dataframe.
+    names, dataframe = MASSAextraction.name_extraction(mols_h)
+    # It defines a list of what biological activities are being extracted.
+    biological_activity = MASSAextraction.the_biological_handler(
+        sdf_property_names, number_bioact, bioactivities_as_args)
+    # It adds the biological activities to the dataframe.
+    dataframe = MASSAextraction.list_activities(dataframe, biological_activity)
+
+    # Get fingeprint and other descriptors:
+    # Get physicochemical descriptors.
+    dataframe = MASSAdescriptors.physicochemical_descriptors(dataframe)
+    # Get AtomPairs fingerprint.
+    dataframe = MASSAdescriptors.atompairs_fingerprint(dataframe)
+
+    # Normalizes physicochemical and biological properties.
+    # Creates matrices for the three domains (struc, phys-chem, bio):
+    bio_matrix, phch_matrix, fp_matrix = MASSApreparation.normalizer_or_matrix(
+        dataframe, biological_activity)
+
+    # PCA:
+    # PCA for the biological domain.
+    bio_pca = MASSApreparation.pca_maker(bio_matrix, npcs, svd_parameter)
+    # PCA for the physicochemical domain.
+    phch_pca = MASSApreparation.pca_maker(phch_matrix, npcs, svd_parameter)
+    # PCA for the structural domain.
+    fp_pca = MASSApreparation.pca_maker(fp_matrix, npcs, svd_parameter)
+
+    # First clustering (HCA):
+    # It performs HCA clustering without generating the dendrogram for the biological domain.
+    leaves_cluster_bio, bio_hca, linkage_bio, cutoff_bio = MASSAcluster.hca_clusters(
+        bio_pca, names, 'bio', directoryfile_output, extension_type, linkage_method)
+    # It performs HCA clustering without generating the dendrogram for the physicochemical domain.
+    leaves_cluster_phch, phch_hca, linkage_phch, cutoff_phch = MASSAcluster.hca_clusters(
+        phch_pca, names, 'PhCh', directoryfile_output, extension_type, linkage_method)
+    # It performs HCA clustering without generating the dendrogram for the structural domain.
+    leaves_cluster_fp, fp_hca, linkage_fp, cutoff_fp = MASSAcluster.hca_clusters(
+        fp_pca, names, 'FP', directoryfile_output, extension_type, linkage_method)
+
+    # It adds the biological cluster identification to the spreadsheet.
+    dataframe = MASSApreparation.organize_df_clusterization(
+        dataframe, bio_hca, 'bio')
+    # It adds the physicochemical cluster identification to the spreadsheet.
+    dataframe = MASSApreparation.organize_df_clusterization(
+        dataframe, phch_hca, 'PhCh')
+    # It adds the structural cluster identification to the spreadsheet.
+    dataframe = MASSApreparation.organize_df_clusterization(
+        dataframe, fp_hca, 'FP')
+
+    # Second clustering (Kmodes):
+    # It creates a matrix with cluster identifications for each of the three domains for Kmodes.
+    matrix_for_kmodes = MASSApreparation.organize_for_kmodes(dataframe)
+    # It performs Kmodes clustering for the general domain.
+    all_hca = MASSAcluster.kmodes_clusters(matrix_for_kmodes, names)
+    # It adds the general cluster identification to the spreadsheet.
+    dataframe = MASSApreparation.organize_df_clusterization(
+        dataframe, all_hca, 'all')
+
+    # Split into training, test:
+    dataframe, test_or_val_molecules = MASSAsplit.split_train_test_sets(
+        dataframe, training_percent, splitting_strategy)
+
+    # Bar plot of frequencies
+    # (Calculates the percentages of molecules in each cluster for each
+    #  dataset and generates a bar graph for each domain):
+
+    # Biological Bar Plot
+    bio_total, bio_training, bio_test, bio_val = MASSAsplit.freq_clusters(
+        dataframe,
+        directoryfile_output,
+        extension_type,
+        'Cluster_Biological',
+        barplot_xfont_size,
+        splitting_strategy)
+    # Physicochemical Bar Plot
+    phch_total, phch_training, phch_test, phch_val = MASSAsplit.freq_clusters(
+        dataframe,
+        directoryfile_output,
+        extension_type,
+        'Cluster_Physicochemical',
+        barplot_xfont_size,
+        splitting_strategy)
+    # Structural Bar Plot
+    fp_total, fp_training, fp_test, fp_val = MASSAsplit.freq_clusters(
+        dataframe,
+        directoryfile_output,
+        extension_type,
+        'Cluster_Structural',
+        barplot_xfont_size,
+        splitting_strategy)
+    # General Bar Plot
+    all_total, all_training, all_test, all_val = MASSAsplit.freq_clusters(
+        dataframe,
+        directoryfile_output,
+        extension_type,
+        'Cluster_General',
+        barplot_xfont_size,
+        splitting_strategy)
+
+    # Verifying percentages:
+    # For biological domain:
+    bio_ok = returns_zero(bio_total, bio_test, bio_val)
+    # For physicochemical domain:
+    phch_ok = returns_zero(phch_total, phch_test, phch_val)
+    # For structural domain:
+    fp_ok = returns_zero(fp_total, fp_test, fp_val)
+    ok = [bio_ok, phch_ok, fp_ok]
+    max_iters = 0
+
+    # Redo the distribution in case of errors (up to 10 times):
+    while (True in ok) and (max_iters < 10):
+        # Split into training, test:
+        dataframe, test_or_val_molecules = MASSAsplit.split_train_test_sets(
+            dataframe, training_percent, splitting_strategy)
+
+        # Bar plot of frequencies (Calculates the percentages of molecules in each
+        # cluster for each dataset and generates a bar graph for each domain):
+
+        # Biological Bar Plot:
+        bio_total, bio_training, bio_test, bio_val = MASSAsplit.freq_clusters(
+            dataframe, directoryfile_output, extension_type,
+            'Cluster_Biological', barplot_xfont_size, splitting_strategy
+        )
+        # Physicochemical Bar Plot
+        phch_total, phch_training, phch_test, phch_val = MASSAsplit.freq_clusters(
+            dataframe, directoryfile_output, extension_type,
+            'Cluster_Physicochemical', barplot_xfont_size, splitting_strategy
+        )
+        # Structural Bar Plot
+        fp_total, fp_training, fp_test, fp_val = MASSAsplit.freq_clusters(
+            dataframe, directoryfile_output, extension_type,
+            'Cluster_Structural', barplot_xfont_size, splitting_strategy
+        )
+        # General Bar Plot
+        all_total, all_training, all_test, all_val = MASSAsplit.freq_clusters(
+            dataframe, directoryfile_output, extension_type,
+            'Cluster_General', barplot_xfont_size, splitting_strategy
+        )
+
+        # Verifying percentages:
+
+        # For biological domain:
+        bio_ok = returns_zero(bio_total, bio_test, bio_val)
+        # For physicochemical domain:
+        phch_ok = returns_zero(phch_total, phch_test, phch_val)
+        # For structural domain:
+        fp_ok = returns_zero(fp_total, fp_test, fp_val)
+        ok = [bio_ok, phch_ok, fp_ok]
+        max_iters += 1
+
+    # Write distribution information to log file:
+    bio_distr = 'Biological Distribution'
+    MASSAsplit.log_of_distributions(
+        bio_distr, bio_total, bio_training,
+        bio_test, bio_val, splitting_strategy,
+        writelog
+    )
+    phch_distr = 'Physicochemical Distribution'
+    MASSAsplit.log_of_distributions(
+        phch_distr, phch_total, phch_training,
+        phch_test, phch_val, splitting_strategy,
+        writelog
+    )
+    fp_distr = 'Structural (FP) Distribution'
+    MASSAsplit.log_of_distributions(
+        fp_distr, fp_total, fp_training,
+        fp_test, fp_val, splitting_strategy,
+        writelog
+    )
+    all_distr = 'General Distribution'
+    MASSAsplit.log_of_distributions(
+        all_distr, all_total, all_training,
+        all_test, all_val, splitting_strategy,
+        writelog
+    )
+    writelog.close()
+
+    # Plot HCAs:
+    if flag_dendrogram == True:
+        print('\nGenerating dendrogram images. Please wait...')
+        MASSAcluster.hca_plot(
+            linkage_bio, names, leaves_cluster_bio,
+            cutoff_bio, 'bio', directoryfile_output,
+            extension_type, dendrogram_xfont_size, test_or_val_molecules
+        )  # Bio_Plot: Plot the HCA dendrogram
+        MASSAcluster.hca_plot(
+            linkage_phch, names, leaves_cluster_phch,
+            cutoff_phch, 'PhCh', directoryfile_output,
+            extension_type, dendrogram_xfont_size, test_or_val_molecules
+        )  # phch_Plot: Plot the HCA dendrogram
+        MASSAcluster.hca_plot(
+            linkage_fp, names, leaves_cluster_fp,
+            cutoff_fp, 'FP', directoryfile_output,
+            extension_type, dendrogram_xfont_size, test_or_val_molecules
+        )  # fp_Plot: Plot the HCA dendrogram
+
+    # Output management:
+    # It adds, for each molecule, the values of the calculated properties, the identifications of each cluster and which set the molecule belongs to.
+    MASSAmoloutput.output_mols(dataframe, file_output)
+    print('Completed')

massa_algorithm-1.0.0/MASSA_Algorithm/MASSAargs.py

@@ -0,0 +1,214 @@
+import re
+import os
+import argparse
+import numpy as np
+
+
+def capture_args():
+    """Capture arguments from command-line
+
+    Returns:
+        args: Return the arguments to run the algorithm.
+        For more information read the --help|-h.
+    """
+    # Capturing arguments from command line:
+    parser = argparse.ArgumentParser(
+        prog='MASSA_Algorithm',
+        epilog='For more information visit: https://github.com/gcverissimo/MASSA_Algorithm',
+        description=(
+            'Help for MASSA Algorithm: Molecular data set sampling  '
+            '—  Training-Test Separation'
+        ),
+        usage=(
+            '%(prog)s [-h] [-i <input_file_name>] [-o <output_file_name] '
+            '[-y <splitting_strategy>] [-p <percentage_of_molecules_in_training_set>] '
+            '[-b <number_of_biological_activities_in_input_file>] [-s <activity1>,<activity2>,<activityN>]'
+            '[-n <number_of_principal_components>] [-v <svd_parameter>] [-l <linkage_method] '
+            '[-t <extension_for_images>] [-d <dendrogram_font_size_on_Xaxis>] '
+            '[-x <frequency_bar_plot_font_size_on_Xaxis>] [-f <toggle_dendrogram>] '
+            '[-e <drop_molecules_with_errors]'
+        )
+    )
+    required = parser.add_argument_group('required arguments')
+    required.add_argument('-i', '--input', type=str, help=(
+                          'Input the file containing the dataset or its file path. '
+                          'Recommended to use an .sdf file to avoid errors.'
+                          ), required=True)
+    required.add_argument('-o', '--output', type=str, help=(
+                          'Enter the output file name or file path. '
+                          'Recommended to use an .sdf file to avoid errors. '
+                          'Image files will be saved to a '
+                          'folder within the same directory as the output file.'
+                          ), required=True)
+    optional = parser.add_argument_group('optional arguments')
+    optional.add_argument('-y', '--splitting_strategy', type=str, choices=['tt', 'tt-val'],
+                          metavar='SPLITTING_STRATEGY', default='tt', help=(
+                          'Defines the splitting strategy, either into training and test '
+                          'sets or into training, test, and validation sets. Options = '
+                          '\'tt\', \'tt-val\'. tt, means splitting into training and test sets. '
+                          'tt-val, means splitting into training, test, and validation sets. '
+                          'Default = \'tt\'.'
+                          ))
+    optional.add_argument('-p', '--percentage_of_training', type=float,
+                          choices=[round(i, 2) for i in list(
+                              np.arange(0.00, 1.00, 0.01))],
+                          metavar='PERCENTAGE_OF_TRAINING',
+                          default=0.8, help=(
+                              'Percentage of molecules in training set. '
+                              'Must be a number from 0 to 1. Default = 0.8.'
+                          ))
+    optional.add_argument('-b', '--number_of_biological', type=int, default=1,
+                          help=(
+                              'Number of biological activities that will '
+                              'be used to separate the set into training and test. Default = 1'
+                          ))
+    optional.add_argument('-s', '--the_biological_activities', type=str, default=None,
+                          help=(
+                              'Enter a list with the names of biological activities '
+                              'separated by commas and no spaces. Example: pIC50,pMIC.')
+                          )
+    optional.add_argument('-n', '--number_of_PCs', type=float,
+                          metavar='NUMBER_OF_PRINCIPAL_COMPONENTS', default=0.85, help=(
+                              'Defines the number of principal components to reduce the '
+                              'dimensionality of variables related to biological, physicochemical '
+                              'and structural domains. If the value is a decimal between 0 and 1, '
+                              'the number of principal components is what justifies for '
+                              '(<input number> * 100) percent of the variance. If the value '
+                              'is greater than 1, the number of PCs will be exactly the input '
+                              'integer, but PAY ATTENTION: 1st) If the number of PCs is an integer '
+                              'and equal to or greater than the number of physicochemical '
+                              'properties (7), the PCA step will be bypassed for this domain. '
+                              '2nd) The same for the biological domain. 3rd) If the number of '
+                              'biological activities is less than 3, the PCA step will be '
+                              'bypassed for this domain. Default = 0.85.'
+                          ))
+    optional.add_argument('-v', '--svd_solver_for_PCA', type=str, default='full',
+                          metavar='SVD_SOLVER_FOR_PCA',
+                          help=('See the sklearn.decomposition.PCA topic on '
+                                'https://scikit-learn.org/ '
+                                'for more info. Default = full.'))
+    optional.add_argument('-l', '--linkage_method', type=str,
+                          choices=['complete', 'single', 'ward', 'average',
+                                   'weighted', 'centroid', 'median'], metavar='LINKAGE_METHOD',
+                          default='complete', help=(
+                              'The linkage criterion to use. The algorithm '
+                              'will merge the pairs of cluster that minimize '
+                              'this criterion. Options = complete, single, ward, '
+                              'average, weighted, centroid, median. Default = complete.'
+                          ))
+    optional.add_argument('-t', '--image_type', type=str, default='png',
+                          help=(
+                              'Extension of the image files that will be generated. '
+                              'Suggested = png or svg. Default = png.'
+                          ))
+    optional.add_argument('-d', '--dendrogram_xfont_size', type=int, default=5,
+                          help=(
+                              'Sets the font size on the x-axis '
+                              'of the dendrogram (molecule labels). Default = 5.'
+                          ))
+    optional.add_argument('-x', '--barplot_xfont_size', type=int, default=9,
+                          help=(
+                              'Sets the font size on the x-axis '
+                              'of the bar plot (cluster labels). Default = 9.'
+                          ))
+
+    optional.add_argument('-f', '--dendrogram_plot', type=str, choices=['true', 'false'],
+                          metavar='ENABLE_DENDROGRAM_PLOT', default='true',
+                          help=('Defines whether or not dendrogram images will '
+                                'be generated. Options = true (dendrogram will be generated), '
+                                'false (dendrogram will not be generated). Default = true.'
+                                )
+                          )
+    optional.add_argument('-e', '--drop_errors', type=str, choices=['true', 'false'],
+                          metavar='DROP_MOLECULES_WITH_ERRORS', default='false', help=(
+                          'Ignore chemistry errors, saving only molecules without any errors. '
+                          'Default = \'false\'.'
+                          ))
+    args = parser.parse_args()
+
+    # Definition of arguments:
+    # It captures the input name and directory+name:
+    file_input = args.input
+    # It captures the output name or directory+name:
+    undefined_file_output = args.output
+    # It captures the file extension for images:
+    extension_type = args.image_type
+    # It captures the font size for the x-axis of the dendrogram:
+    dendrogram_xfont_size = int(args.dendrogram_xfont_size)
+    # It captures the font size for the x-axis of the bar plot:
+    barplot_xfont_size = int(args.barplot_xfont_size)
+    # It captures the percentage for training set:
+    training_percent = round(float(args.percentage_of_training), 3)
+    # It captures the number of biological activities:
+    nbio_activities = int(args.number_of_biological)
+    # It captures the input number of PCs:
+    ninput_pcs = args.number_of_PCs
+    # It captures the svd_solver parameter:
+    svd_parameter = args.svd_solver_for_PCA
+    # It captures the linkage method:
+    linkage_method = args.linkage_method
+    # It captures the flag for the dendrogram plot.
+    flag_dendrogram = str(args.dendrogram_plot).lower()
+    # It captures the selected splitting strategy.
+    flag_strategy = str(args.splitting_strategy).lower()
+    # It captures whether or not to ignore chemistry errors.
+    drop = str(args.drop_errors).lower()
+
+    if args.the_biological_activities != None:
+        # It creates a list with the names of the biological activities to be searched for.
+        bioactivities_as_args = args.the_biological_activities.split(',')
+    else:
+        bioactivities_as_args = None
+
+    # If a directory path is passed along with the filename it copies only the directory path.
+    if ('\\' in undefined_file_output) or ('/' in undefined_file_output):
+        outputsplitted = re.split('\\\\|/', undefined_file_output)
+        outputsplitted[-1] = ''
+        dir_fileoutput = '/'.join(outputsplitted)
+        del outputsplitted
+    else:  # If only the filename is passed, the directory path is taken by os.getcwd().
+        dir_fileoutput = str(os.getcwd()) + '/'
+
+    if ninput_pcs > 1:
+        npcs = int(ninput_pcs)
+    elif (ninput_pcs > 0) and (ninput_pcs <= 1):
+        npcs = float(ninput_pcs)
+    else:
+        print(' ERROR: The defined number of main components is invalid.')
+        exit()
+
+    if flag_dendrogram == 'true':
+        flag_dendrogram = True
+    elif flag_dendrogram == 'false':
+        flag_dendrogram = False
+    else:
+        print(
+            ' ERROR: ENABLE_DENDROGRAM_PLOT parameter only accepts \'true\' or \'false\'.')
+        exit()
+
+    if drop == 'true':
+        drop = True
+    elif drop == 'false':
+        drop = False
+    else:
+        print(
+            ' ERROR: DROP_MOLECULES_WITH_ERRORS parameter only accepts \'true\' or \'false\'.')
+        exit()
+
+    return (
+        file_input,
+        undefined_file_output,
+        dir_fileoutput,
+        extension_type,
+        dendrogram_xfont_size,
+        barplot_xfont_size,
+        training_percent,
+        nbio_activities,
+        bioactivities_as_args,
+        npcs,
+        svd_parameter,
+        linkage_method,
+        flag_dendrogram,
+        flag_strategy,
+        drop
+    )