BioxML-allergen-epitopes: A Jupyter Notebook repository from trevorpfiz

Epitope Prediction Platform - B-cell and T-cell Epitope Prediction Powered by ESM-3

This is an open source web platform powered by ESM-3 to advance B-cell and T-cell epitope prediction. One of our aims is to discover new allergen epitopes not listed in the IEDB and advance allergy research.

Table of Contents

Demo
Project Details
Technical Details
Installation and Usage
Feedback
Contributing
License
References

Demo

https://devpost.com/software/epitope-prediction-web-platform

(back to top)

Project Details

Apps

Next.js web platform for B-cell and T-cell epitope predictions powered by ESM-3.
FastAPI for hosting ESM-3 and predicting epitopes.
Tools FastAPI for hosting DTU Health Tech tools.

Features

Authentication: Anonymous Sign-Ins with Supabase Auth.
Epitope Predictions: ESM-3 for linear B-cell, conformational B-cell, MHC-I, and MHC-II epitope predictions.
Web Dashboard: Next.js app for managing epitope predictions.

(back to top)

Technical Details

Tech Stack

.github
  └─ workflows
        └─ CI with pnpm cache setup
.vscode
  ├─ Recommended extensions and settings for VSCode users
  └─ Multi-root Workspaces for smoother python experience in monorepo
apps
  ├─ nextjs
  |   ├─ Next.js 14
  |   ├─ React 18
  |   ├─ Tailwind CSS
  |   └─ E2E Typesafe API Server & Client
  ├─ fastapi
  |   ├─ FastAPI for uploading and processing protein sequences
  |   ├─ ESM-3 for epitope predictions
  └─ tools-fastapi
      └─ FastAPI to call DTU Health Tech tools hosted on EC2

notebooks
  └─ working with the models
packages
  ├─ api
  |   ├─ tRPC v11 router definition.
  |   └─ Generated TypeScript client from FastAPI OpenAPI spec.
  ├─ db
  |   └─ Typesafe db calls using Drizzle & Amazon RDS
  ├─ ui
  |   └─ shadcn/ui.
  └─ validators
      └─ Zod schemas for repo-wide type-safety and validation.
tooling
  ├─ eslint
  |   └─ shared, fine-grained, eslint presets
  ├─ prettier
  |   └─ shared prettier configuration
  ├─ tailwind
  |   └─ shared tailwind configuration
  ├─ github
  |   └─ shared github actions
  └─ typescript
      └─ shared tsconfig you can extend from

In this project, we use @epi as a placeholder for package names. As a user, you might want to replace it with your own organization or project name. You can use find-and-replace to change all the instances of @epi to something like @my-company or @project-name.

(back to top)

Installation and Usage

For ML Engineers

1. Clone the repo and navigate to notebooks

git clone https://github.com/trevorpfiz/BioxML-allergen-epitopes.git
cd BioxML-allergen-epitopes/notebooks

2. VS Code-GitHub-Google Colab

https://peter-jp-xie.medium.com/develop-colab-notebooks-with-visual-studio-code-de830dde9baa

For Web Developers

1. Setup dependencies

# Install dependencies
pnpm i

# Configure environment variables.
# There is an `.env.example` in the root directory you can use for reference
# Ensure that the POSTGRES_URL is in the same format as in the example
cp .env.example .env

# Push the Drizzle schema to your database (w/ drizzle-kit push)
pnpm db:push

# Or use migrations (w/ drizzle-kit generate and drizzle-kit migrate)
pnpm db:generate
pnpm db:migrate

NOTE: Migrations seem preferable for Supabase. Still figuring out the best way to do migrations for local development/branching. https://twitter.com/plushdohn/status/1780126181490135371

2. Setup Supabase

Go to the Supabase dashboard and create a new project.
Under project settings, retrieve the environment variables reference id, project url & anon public key and paste them into .env in the necessary places. You'll also need the database password you set when creating the project.
Under Auth, configure any auth provider(s) of your choice. This repo is using Github for Web and Apple for Mobile.
If you want to use the Email provider and email confirmation, go to Auth -> Email Templates and change the Confirm signup from {{ .ConfirmationURL }} to {{ .RedirectTo }}&token_hash={{ .TokenHash }}&type=signup, according to https://supabase.com/docs/guides/auth/redirect-urls#email-templates-when-using-redirectto. .RedirectTo will need to be added to your Redirect URLs in the next step.
Under Auth -> URL Configuration, set the Site URL to your production URL and add http://localhost:3000/** and https://*-username.vercel.app/** to Redirect URLs as detailed here https://supabase.com/docs/guides/auth/redirect-urls#vercel-preview-urls.
Set up a trigger when a new user signs up: https://supabase.com/docs/guides/auth/managing-user-data#using-triggers. You can run this in the SQL Editor.

-- inserts a row into public.profile
create function public.handle_new_user()
returns trigger
language plpgsql
security definer set search_path = public
as $$
begin
  insert into public.epi_profile (id, email, name, image)
  values (
    new.id,
    new.email,
    COALESCE(
      new.raw_user_meta_data ->> 'name',
      new.raw_user_meta_data ->> 'full_name',
      new.raw_user_meta_data ->> 'user_name',
      'Guest User'
    ),
    new.raw_user_meta_data ->> 'avatar_url'
  )
  on conflict (id) do update set
    email = excluded.email,
    name = excluded.name,
    image = excluded.image;
  return new;
end;
$$;

-- trigger the function every time a user is created
create trigger on_auth_user_created
  after insert on auth.users
  for each row execute procedure public.handle_new_user();

-- trigger the function when a user signs in/their email is confirmed to get missing values
create trigger on_auth_user_verified
  after update on auth.users
  for each row when (
    old.last_sign_in_at is null
    and new.last_sign_in_at is not null
  ) execute procedure public.handle_new_user();

-- drop a trigger if needed
drop trigger "on_auth_user_verified" on auth.users;

Remove access to the public schema as we are only using the server

By default, Supabase exposes the public schema to the PostgREST API to allow the supabase-js client query the database directly from the client. However, since we route all our requests through the Next.js application (through tRPC), we don't want our client to have this access. To disable this, execute the following SQL query in the SQL Editor on your Supabase dashboard:

REVOKE USAGE ON SCHEMA public FROM anon, authenticated;

Note: This means you also don't need to enable row-level security (RLS) on your database if you don't want to.

(back to top)

Feedback

Share your thoughts in Discussions

(back to top)

Contributing

We welcome contributions! Find out how you can contribute to the project in CONTRIBUTING.md: Contributing Guidelines

Made with contrib.rocks

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

References

This repo originates from create-t3-turbo. Feel free to check out the project if you are running into issues with running/deploying the starter.

Thanks as well to the following:

SEMA 2.0 for fueling the original idea of this project.
next-fast-turbo for the learnings on how to bring FastAPI into the project.

(back to top)