$Id: common_EN.txt 10528 2023-03-14 11:02:08Z saulius $

Visualisation of 3D protein structures
======================================

The main goal of this assignment is to familiarise yourself with the
SCOP and CATH protein classes and to learn how to visualise secondary
structures of proteins using Rasmol or Jmol programs.

Tasks that must be carried out in this assignment are the following:

-- Fetch the protein models assigned to you from the PDB data bank;

-- Determine which SCOP and CATH classes do these protein structures
   belong to;

-- Demonstrate various methods to depict protein structures and their
   selected darts using Rasmol or Jmol programs. Learn how to use both
   GUI and command-based user interfaces of these programs;

-- Write a small shell program to generate a picture of a molecule
   from the PDBx structure file using the supplied parameters;

-- Describe the results in a report.

STEPS TO ANALYSE A PROTEIN STRUCTURE
====================================

1. Download PDB structures assigned to you in the mmCIF (PDBx) format.

2. Determine by visual inspection on the 3D graphics which SCOP and
   CATH class do these structures belong to.

3. Depict the protein structures assigned to you in different
   ways. Use Jmol or Rasmol programs for that. With each of the
   structure, perform the following tasks:

3.1 Depict the whole structure as:

    3.1.1 an C-alpha atom backbone;
    3.1.2 a whole atom CPK model;
    3.1.3 a wireframe model;
    3.1.4 a cartoon model.

3.2 Colour your structure by:

    3.2.1 the atom type (apply this to the CPK and wireframe models);
    3.2.2 the secondary structure (apply this to the C-alpha backbone
          and cartoon models);
    3.2.3 protein chain;
    3.2.4 temperature factor (B-factor);

3.3 Depict only helices in your structure;

3.4 Depict only beta-sheets in your structure;

3.5 Select a single helix in your structure. With this helix:

    3.5.1 Display hydrogen bonds in this helix;
    3.5.2 Save a Rasmol/Jmol script (history) file of you operations;
    3.5.3 Highlight the hydrogen bonds (change their line thickness
          and colour);
    3.5.4 Depict the select helix a a main-chain trace (including all
          atoms that are not in side chains); show/leave the hydrogens
          bonds on.

3.6 Depict one parallel and one anti-parallel beta-sheet (fragment):

    3.6.1 depict the sheet as a CPK model;
    3.6.2 depict the sheet as a main chain model;

4. Use your 'pdbx-draw-secondary' script to generate pictures for the
   secondary structures that you have displayed in the steps 3.3 –
   3.6. The description of the program is given in the section
   "PROGRAM".

5. Describe all steps of your exercise in such a way that it can be
   reproduced independently:

   -- provide detailed provenance of your input data (when and from
      which URLs have you downloaded the data; which database and
      which version is it taken from); make sure that your downloads
      are reproducible;

   -- create a table with the results from the step 2;

   -- describe all stages of the step 3; provide the commands that you
      have used to analyse and depict the structures;

   -- provide commands that you have used to generate pictures from
      stage 4 (the call to you program and its arguments);

   The general requirements for the description are in the chapter
   "REPORT".

PROGRAM
=======

The program MUST read a single PDBx format file and write out a
corresponding PNG or PNM format image file. The program should depict
a specified part of the chain as a wireframe model, colour atoms by their
chemical types and highlight the hydrogen bonds in the secondary
structures.

The program name should be:
pdbx-draw-secondary

Program usage:
pdbx-draw-secondary '*A and 10-111,212-221' inp.pdbx out.png
pdbx-draw-secondary -r rotation.ras '*A and 10-111,212-221' inp.pdbx out.png

The first three position (i.e. non-option) arguments are required:

-- the first argument is a selection statement that describes the part
   of the chain to be displayed;

-- the second argument is the name of the input PDBx file;

-- the third argument is the name of the output PNG or PNM file.

The program MUST also accept an optional argument '-r' with a
value. The value SHOULD be the name of a file with a rotation
commands that determine the ultimate model orientation in the
picture. The orientation setting commands MUST be applied to the
selected atoms before they are rendered in the output picture.

FILE FORMATS
============

The 'pdbx-draw-secondary' MUST accept the following files:

-- protein atom coordinate input file: PDBx;
-- rotation matrix format: Rasmol or Jmol commands;
-- selection of the atoms: Rasmol or Jmol selection statement;
-- image output format: PNG or PNM.

DIAGNOSTICS
===========

The 'pdbx-draw-secondary' program should diagnose:

-- missing or unreadable input files;

-- incorrect file formats (the format MUST NOT be inferred from the
   file extension!);

-- incorrect input commands syntax;

-- situations when the image can not be created.

The native build-in diagnostics of Rasmol or Jmol may be used, but the
tests for the corresponding 'pdbx-draw-secondary' program behaviour
MUST be provided. Return status and output file format MUST be checked
in the 'pdbx-draw-secondary' program.

Use the standard course Makefile to test your program.

GENERATION OF THE IMAGES
========================

Provide a GNU Makefile with the rules that generate your images. Use
pattern rules in order to avoid code repetition. Implement the
well-known targets 'all', 'clean' and 'distclean'; declare them as
.PHONY.

When a 'make' command is run in the directory with your Makefile, all
images necessary for your report MUST be generated. The subsequent
'make' command MUST report that all images are up-to-date
(e.g. "nothing to be made for 'all'"). The 'make clean' command must
remove intermediate files if such files exist; the 'make distclean'
command must remove all files generated by Make.

Use your program 'pdbx-draw-secondary' to generate pictures.

REPORT
======

Write a report of your investigation, approx. two A4 pages large (use
9-10 point size font). Provide the metadata and the references as
required for the University's course works or BSc theses. Provide your
report in the PDF file format.

Insert a single picture from your generated pictures:

- If each of your assigned proteins; if a protein is a multi-domain
  proteins, depict one domain that highlights each of the four main
  SCOP classes. Use the display mode (trace, backbone, cartoon, etc.)
  that shows best the secondary and the tertiary structure of your
  protein.

- Add one image of each of the protein secondary structure element:
  alpha-helix, parallel and anti-parallel beta sheet in a "wireframe"
  mode. Show the hydrogen bonds.