GSoC 2024: Interactive Web Interface for Selector

[JackyZzZz]

Selector: Interactive Web Interface for Chemical Subset Selection

Intro

Dear contributors of QC-Devs,

My name is Jun Xia. I have been selected as a GSoC contributor for our Selector package this year (2024) . I will work on creating a web interface for our Selector package using Streamlit, and I will leverage Docker and Github Actions to deploy the complete application on HuggingFace.

Currently, our Selector package is a complete backend application, which makes it difficult for scientists or scholars with minimal coding experience to use our tool. Fortunately, Streamlit simplifies the process of creating interfaces for data-based tools, and I am excited to learn and use this new Python framework for the first time in a real-world application.

You can find the most updated details in the progress log below. (I can be a bit chatty, but I believe this helps me stay motivated and on track with our timeline.) You can also check out our weekly meeting notes in the discussion panel.

I am open to suggestions and ideas, so feel free to @ me below to discuss your thoughts.

I am looking forward to a great summer with our project!

Roadmap

Note that more details about the roadmap may be added to this list as I start to work on them.

• A Web Interface to Perform Subset Selection

  • Home Page
  • Distance based methods
    • DISE
    • MaxMin
    • MaxSum
    • OptiSim
  • Partition based methods
    • GridPartition
    • Medoid
  • Converter Page that transform SMILES and SDF chemical formats into matrix

• Establish a CI/CD Process Using Docker and GitHub Actions

  • Create a suitable DOCKERFILE
  • Setting up Github Actions pipeline
  • Publish the image on DockerHub

• Deploy the Interface on HuggingFace

Meeting Notes

• Week 0-1
  • Meeting Notes for GSoC (5/9/2024) #205
  • Meeting Notes for GSoC (5/27/2024) #209
• Week 3
  • Meeting Notes for GSoC (6/10/2024) #211
• Week 4
  • Meeting Notes for GSoC (6/18/2024) #215
• Week 6
  • Meeting Notes for GSoC (7/2/2024) #226
• Week 7
  • Meeting Notes for GSoC (7/12/2024) #232
• Week 10
  • Meeting Notes for GSoC (8/1/2024) #233
• Week 11
  • Meeting Notes for GSoC (8/8/2024) #241
• Week 12
  • Meeting Notes for GSoC (8/15/2024) #247
• Week 13
  • Meeting Notes for GSoC (8/22/2024) #253
  • Meeting Notes for GSoC (8/29/2024) #255

Blog

I decided to write blogs to document my progress throughout the project as well. Check it out below😍

• Week 1-3
• Week 4-5

[JackyZzZz]

@FanwangM I just made this doc to track the overall progress of our project instead of creating a new discussion for every issue I have. We can also use this as the work log for the final GSoC demonstration page, which I think will be kind of cool.

What do you think of the current layout? Will this be okay? I plan to just have each algorithm or function as a separate page on the left sidebar. Let me know your thoughts!

Before I dive into implementing any details, I do have a question about the input thou. As we discussed in our last meeting, the output will be just a list or 2D matrix in most cases. However, the input seems like a 2D matrix to me such as for MaxMin, and it was generated using the helper function generate_synthetic_data in the documentation example and unit tests. I am trying to picture how will the user provides the input if using our streamlit application then. Do you expect them to have the dataset like the 2D matrix generated by generate_synthetic_data in the example already, or should we also wrap the function generate_synthetic_data so that users without a dataset can also see what our tool might do for them. I was reading our documentation and I noticed that it states our package can also supports importation of dataset in formats such as SDF, etc... So I am trying to picture what this might look like in the interface.

Also, I have listed out the APIs or algorithms of our package, could you verify if it is accurate? Hope I didn't miss anything :-) I will wrap each one of them as a separate page in our application in the upcoming weeks.

[FanwangM]

Hi @JackyZzZz. Thank you for the posts. I noticed that you have a feature added to the main branch, which is sub-optimal. I would just add a feature branch (you can name it whatever you like) and then add new prototyping into that branch. The main branch in your repo then can be used to align with the main branch in the theochem. Some code examples show how this look like

# suppose you are working on a branch called app

# check out the feature branch
git checkout app
# add new codes
# git add your new files and changes
git commit
# git push to app branch
git push origin app
# make a pull request to theochem/main

# once the pull request is merged

# update your own master branch
git check main
# add theochem repo as upstream
git remote add theochem [email protected]:theochem/Selector.git
git pull theochem main
git push origin main

By doing so, we can always keep our own main branch updated to the theochem one.

I will write more about your question soon.

[FanwangM]

For the input and output of the function. Please don't get too distracted by the notebook in https://github.com/theochem/Selector/blob/main/book/content/starting.ipynb. Instead, starting with

Selector/selector/methods/distance.py

Lines 39 to 121 in 55bf0b9

	class MaxMin(SelectionBase):
	"""Select samples using MaxMin algorithm.
	MaxMin is possibly the most widely used method for dissimilarity-based
	compound selection. When presented with a dataset of samples, the
	initial point is chosen as the dataset's medoid center. Next, the second
	point is chosen to be that which is furthest from this initial point.
	Subsequently, all following points are selected via the following
	logic:
	1. Find the minimum distance from every point to the already-selected ones.
	2. Select the point which has the maximum distance among those calculated
	in the previous step.
	In the current implementation, this method requires or computes the full pairwise-distance
	matrix, so it is not recommended for large datasets.
	References
	----------
	[1] Ashton, Mark, et al., Identification of diverse database subsets using
	property‐based and fragment‐based molecular descriptions, Quantitative
	Structure‐Activity Relationships 21.6 (2002): 598-604.
	"""
	def __init__(self, fun_dist=None):
	"""
	Initializing class.
	Parameters
	----------
	fun_distance : callable
	Function for calculating the pairwise distance between sample points.
	`fun_dist(X) -> X_dist` takes a 2D feature array of shape (n_samples, n_features)
	and returns a 2D distance array of shape (n_samples, n_samples).
	"""
	self.fun_dist = fun_dist
	def select_from_cluster(self, X, size, labels=None):
	"""Return selected samples from a cluster based on MaxMin algorithm.
	Parameters
	----------
	X: ndarray of shape (n_samples, n_features) or (n_samples, n_samples)
	Feature matrix of `n_samples` samples in `n_features` dimensional feature space,
	or the pairwise distance matrix between `n_samples` samples.
	If `fun_dist` is `None`, the `X` is assumed to be a square pairwise distance matrix.
	size: int
	Number of sample points to select (i.e. size of the subset).
	labels: np.ndarray
	Indices of samples that form a cluster.
	Returns
	-------
	selected : list
	List of indices of selected samples.
	"""
	# calculate pairwise distance between points
	X_dist = X
	if self.fun_dist is not None:
	X_dist = self.fun_dist(X)
	# check X_dist is a square symmetric matrix
	if X_dist.shape[0] != X_dist.shape[1]:
	raise ValueError(f"The pairwise distance matrix must be square, got {X_dist.shape}.")
	if np.max(abs(X_dist - X_dist.T)) > 1e-8:
	raise ValueError("The pairwise distance matrix must be symmetric.")
	if labels is not None:
	# extract pairwise distances from full pairwise distance matrix to obtain a new matrix
	# that only contains pairwise distances between samples within a given cluster
	X_dist = X_dist[labels][:, labels]
	# choosing initial point as the medoid (i.e., point with minimum cumulative pairwise
	# distances to other points)
	selected = [np.argmin(np.sum(X_dist, axis=0))]
	# select following points until desired number of points have been obtained
	while len(selected) < size:
	# determine the min pairwise distances between the selected points and all other points
	min_distances = np.min(X_dist[selected], axis=0)
	# determine which point affords the maximum distance among the minimum distances
	# captured in min_distances
	new_id = np.argmax(min_distances)
	selected.append(new_id)
	return selected

makes more sense, which actually shows what is input and output for MaxMin. And the cell number 8 in https://github.com/theochem/Selector/blob/main/book/content/starting.ipynb provides an example for the input and output of MaxMin.

For now, the input of our app includes

• A feature matrix or distance matrix, which can just be a CSV or Excel file, or a numpy array (npz or npy files) for the moment (required).
• number of data points we need to select (required);
• A cluster label list from a CSV or Excel file (optional).

Then for the algorithms like MaxMin, we will also allow the user to specify the parameters for these algorithms.

As for output, we can only provide people with a list of selected indices for now. Hope this clarifies a little. For the choice you mentioned of generating molecular features, we can leave for the later stage of this program, where we can have a new functionality of generating molecular features based on chemical structures given in SDF files or SMILES strings.

Hope this clarifies a little. If any part is unclear, please feel free to ask. @JackyZzZz

[JackyZzZz]

Hi Fanwang! Thank you so much for your advice! I've created a dev-branch on my forked version, and I reverted the main branch of my forked version to align with our repo's status. I will do all the development in dev-branch from now on.

I will also take a deeper look at the input, and I will see if I can make MaxMin works first.

[FanwangM]

Please feel free to post any questions that you may have. I am here to help!
@JackyZzZz

[JackyZzZz]

@FanwangM I made the first draft version of MaxMin algorithm. Of course there are still many areas for improvement such as error handling, but I think currently it's a simple working prototype. You can check my progress log above for more detail, and I've also put a demo there. Let me know what you think😊

Also, I am curious what frequency would you like me to open for PRs? Do you think it might be a good idea to open one when I finish a function such as MaxMin? As we discussed in our last meeting, unit tests might hold until we finish all the basic functionalities first. So I am wondering if we can still open PRs since they don't have unit tests associated with them yet if that's okay.

[PaulWAyers]

@JackyZzZz you can always open "draft" pull requests when you want feedback but don't think it is ready to be merged yet. We tend to favor many smaller pull requests, which are easier to review. Plus, early feedback is better than late criticism.

[JackyZzZz]

Hi @FanwangM , I was able to set up the Github Actions pipeline today🚀 However, I encountered a problem when I try to raise a pull request. Since I cleaned the commit history of binary files, it will result a situation like this when I raise a PR:

Do you have any suggestions for this maybe? You can refer to the Progress Log above for more detail of what I did. 6/13/2024 and 6/12/2024 might be helpful. Let me know what you think~

[JackyZzZz]

We can also discuss this in our meeting next week I think since it's probably late in your timezone. I can work on other interfaces in the meantime until our next meeting😊 I'll also do more research to see if there is an optimal way of solving this instead of rewriting the entire git history to remove them.

[FanwangM]

Thanks for the clarification.
I will try to take a closer look today. Will update you soon. @JackyZzZz

[FanwangM]

I still have some questions about understanding the situation. I think it might be better to discuss this in our upcoming meeting.

One major question so far is why the highlighted commits are in your uncleaned branch? They should be part of hold history, and should not belong to your branch. @JackyZzZz

[JackyZzZz]

@FanwangM That's because I forgot to save a backup branch before I cleaned the git history... Currently the uncleaned branch is all the changes I have to date along with a git rebase with our original main branch, which there are some merge conflicts involved in when I did that. That's why some commits from earlier showed up in my uncleaned branch too.

[JackyZzZz]

@FanwangM I just realized that there is a "cheating" way to do this without messing our repo directly😂 We can simply do the filter-branch during Github Action workflow. This way, the cleaning process will just be temporary for making HuggingFace accept our push, but our repo will maintain in a clean way. Of course if we want to fix the problem completely, we can also discuss it in our next meeting to see if it's necessary to remove it from our git history. I think it's not really necessary since it's probably only HuggingFace that has this weird restriction... Anyway, I can finally open a pull request now😍

[JackyZzZz]

Hi @FanwangM,

I was working on making the matrix converter work for our interface. I did a small experiment on the code snippet you provided me here. Here is my testing script:

    # Example SMILES strings
    smiles_list = ["CCO", "CCN", "CCC"]

    # Convert SMILES to RDKit molecules
    molecules = [Chem.MolFromSmiles(smiles) for smiles in smiles_list]

    for mol in molecules:
        if mol is None:
            print("Invalid molecule found.")
        else:
            print(Chem.MolToSmiles(mol))

    # Visualize the molecules
    img = Draw.MolsToImage(molecules)
    img.show()

    # Initialize the FingerprintGenerator with the RDKit molecules
    fp_generator = FingerprintGenerator(molecules)

    # Compute fingerprints and get the feature matrix
    feature_matrix = fp_generator.compute_fingerprint(fp_type = "ECFP", n_bits = 128)

    print(type(feature_matrix))
    print(feature_matrix)

However, the output I received is all 0-based, so I think something might went wrong here. I am not very familiar with the chemical part. Do you think it's a problem with my input or the implementation itself? Could you give any suggestions or examples on how to use the convert function here? Thanks!

<class 'pandas.core.frame.DataFrame'>
     0    1    2    3    4    5    6    ...  121  122  123  124  125  126  127
CCO    0    0    1    0    0    0    0  ...    0    0    0    0    0    0    0
CCN    0    0    0    0    0    0    0  ...    0    0    0    0    0    0    0
CCC    0    0    0    0    0    0    0  ...    0    0    0    0    0    0    0

[3 rows x 128 columns]

Process finished with exit code 0

[FanwangM]

Sorry for the late reply. Did you count how many zeros and ones in each row?

[JackyZzZz]

@FanwangM BTW I think I might've found the reason why our workflow keeps failing. Since we ran the workflow through a pull request trigger, the setting of Github doesn't allow workflow triggered by pull request to access the secrets since that might cause security issues. My version worked because the workflow was triggered by push request to my own forked version. The details can be found through this guide. Hope we can solve this during our next meeting🙏