De Novo Genome Assembly with AI-Assisted Data Analysis

Hands-on Project

Part 1. Set Up the Codex/Claude Project

1.1 Set up Codex or Claude Code

If this is your first time using Codex or Claude Code on BioHPC, follow the appropriate setup instructions:

Codex: Codex setup instructions

Claude Code: Claude Code setup instructions

1.2 Connect to your assigned server.

Find your assigned server on this page:

https://biohpc.cornell.edu/ww/machines.aspx?i=172

• On Cornell campus or using Cornell VPN:

  xxxxxxxxxx
  ssh your_user_id@cbsuxxxxxx.biohpc.cornell.edu
  

• Off campus without VPN:

  xxxxxxxxxx
  ssh your_user_id@cbsulogin.biohpc.cornell.edu
  
  ssh cbsuxxxxxx
  

1.3 Prepare your working directory and data

x
mkdir /workdir/$USER

cp -r /shared_data/assembly_ws /workdir/$USER/

cd /workdir/$USER/assembly_ws

ls -l

You should see :

• PacBio sequencing data:

  • SRR10238607_subreads.fastq.gz

• AI agent skill files:

  • ASSEMBLY_SKILL.md

  • BRAKER4_SKILL.md

• Supporting files for genome annotation

  • rnaseq

  • protein

1.4 Inspect the two skill files.

x
cat ASSEMBLY_SKILL.md
cat BRAKER4_SKILL.md

• The two skill files are Markdown-formatted text files that contain protocols for genome assembly and genome annotation.

• You may download these two files to your laptop and open them with a Markdown viewer, such as the Chrome browser with a Markdown-viewing extension installed.

Part 2. Genome Assembly

2.1 Start Codex or Claude Code from the project directory

Start the AI agent from your project directory:

xxxxxxxxxx
cd /workdir/$USER/assembly_ws

codex
# or
claude

Each Codex or Claude Code session is associated with a project directory. Files in this directory provide the working context for the agent and are where the scripts, logs, and analysis results will be created.

During a session, Codex or Claude Code may ask you to make a selection or approve an action. When a numbered list of options is displayed, press the corresponding number key to make your selection.

2.2 Load the BioHPC agent instructions

Enter the following prompt:

x
Load /programs/ai_pipelines/AGENTS.md

The AGENTS.md file contains instructions and guardrails for working in the BioHPC computing environment. It provides information such as how software should be run, where analysis files should be stored, and what actions the agent should or should not perform.

2.3 Load the genome assembly skill

Enter:

x
Load ASSEMBLY_SKILL.md

The skill file provides the agent with the protocol for genome assembly and quality control.

2.4 Ask the agent to create the analysis script

Enter:

xxxxxxxxxx
Create a script to do genome assembly and QC.

The agent will use the instructions in ASSEMBLY_SKILL.md to create the analysis workflow.

Before continuing, inspect what the agent created. You can ask:

xxxxxxxxxx
Explain the script you created.

or:

xxxxxxxxxx
What files will this script generate?

2.5 Run the analysis in a persistent screen session

Genome assembly may take hours. If you do not want to wait for the assembly to finish, skip step 2.5, and move on to 2.6 to copy the precomputed results.

If you prefer to run the script by yourself. The analysis should be run inside a persistent screen session so that it continues running if your SSH connection is interrupted.

Start a second SSH terminal, copy-paste the commands provided by the agent to start "screen" session and run the analysis.

To detach from a screen session without stopping the analysis:

Press Ctrl+A, release the keys, and then press D.

You can then log out of the server while the analysis continues.

To reconnect to a screen session:

xxxxxxxxxx
screen -r

After starting the computation, you may exit the AI agent if desired by press "ctrl+c".

2.6. Skip the computation and copy the pre-made results

If you do not want to wait for the assembly to finish during the workshop, copy the precomputed results:

x
cp -r /shared_data/assembly_results/* /workdir/$USER/assembly_ws/

2.7 Resume the agent and inspect the results

Return to the project directory:

x
cd /workdir/$USER/assembly_ws

For Codex, resume your previous session:

xxxxxxxxxx
codex resume --last

Then ask the agent to inspect the completed analysis:

xxxxxxxxxx
Check the output in the results directories.

Useful follow-up questions include:

xxxxxxxxxx
Did the analysis complete successfully?
What are the important QC results?
What files should I examine?
Are there any problems with this assembly?
What should I do next?

The agent can inspect the output files and logs, summarize the QC results, identify potential problems, and recommend the next steps.

HTML reports generated by the workflow can be downloaded to your laptop using FileZilla and opened in a web browser.

Part 3. Genome Annotation

3.1 Load the genome annotation skill

Enter:

x
Load BRAKER4_SKILL.md

The skill file provides the agent with the protocol for genome annotation using BRAKER4.

You may ask the agent to briefly explain the workflow before proceeding:

xxxxxxxxxx
What are you going to do?

3.2 Ask the agent to create the annotation script

Enter:

x
Create a script to do genome annotation on the primary assembly. Use the files rnaseq and protein directroy as training data. 

Hifiasm produces several representations of the genome assembly. In this exercise, we will annotate the primary assembly, which is commonly used as the reference assembly for downstream analysis.

The agent will use the instructions in BRAKER4_SKILL.md and the supporting RNA-seq and protein data provided with the project to create the annotation workflow.

There are two commonly used approaches for eukaryotic genome annotation: BRAKER and Helixer. BRAKER uses evidence such as RNA-seq and protein sequences to guide gene prediction and train species-specific gene prediction models. Helixer uses a pretrained deep-learning model to predict genes directly from the genome sequence and does not require RNA-seq or protein evidence as input. Helixer is a lot faster, but it requires to run on a GPU server. In this hands-on project, the provided BRAKER4_SKILL.md uses the BRAKER4 pipeline. Both approaches have advantages and limitations, and the best choice depends on your organism, the available data, and the goals of your project. For your own research project, you can work with the AI agent to investigate questions such as:

• Should I use BRAKER or Helixer for this genome?

• What are the advantages and limitations of each approach for my organism?

• What RNA-seq and protein evidence should I use for BRAKER?

• How can I obtain and prepare appropriate evidence data?

If you choose BRAKER, the quality and choice of RNA-seq and protein evidence are important. Rather than simply using whatever data are readily available, you can work with the AI agent to identify, evaluate, download, and prepare appropriate evidence for your genome annotation.

3.3 Run the annotation

Genome annotation can be computationally intensive and may require many CPU cores. As in Part 2, follow the agent's instructions and run the analysis in a persistent screen session.

On the relatively low-end computing nodes provided for this workshop, the complete BRAKER4 analysis may take several days. You do not need to wait for it to finish during the workshop.

To continue with the exercise, you can use a set of precomputed annotation results:

x
#run this command in terminal.
tar xvfz /shared_data/assembly_results2/annotation_primary.tar.gz -C /workdir/$USER/assembly_ws

You can then resume the AI agent and ask it to inspect and interpret the precomputed results just as you would with results generated by your own run.

Useful follow-up prompts include:

xxxxxxxxxx
Did the annotation complete successfully?

Summarize the annotation results.

What are the important output files?

Are there any problems with the annotation?

Part 4. Documentation

Documentation is an essential part of reproducible research. An AI agent can help organize the scripts, record how the analysis was performed, and prepare documentation for future use.

Ask the agent to organize and document the project.

Example prompts:

xxxxxxxxxx
Organize all generated scripts into a scripts directory.
Add a README file describing the project and each script.
Write a project summary describing the analysis, input data, software, software versions, and major results. Make it suitable as a starting point for the Methods section of a manuscript.

Finally, inspect the documentation created by the agent. Make sure that it accurately reflects the analyses that were actually performed.

Do not assume that AI-generated documentation is correct. Important details such as software versions, parameters, input files, and results should be verified against the scripts and log files.