PyMOL Wiki - User contributions [en]

Stereo 3D Display Options

2012-09-12T17:26:58Z

Jedgold: /* iZ3D */

This page is for aggregating the latest know-how and links to current Stereo 3D display options best suited for molecular graphics applications like PyMOL. Please strive to provide objective factual information based on first-hand experiences while using the displays for real work and teaching.

Let's figure out together what stereo solutions work well in this brave new post-CRT world!

== Categories ==

* '''[[#Active_Stereo_3D|Active Stereo 3D]]''' -- requires expensive and/or bulky shutter glasses. For decades, this has been the standard solution for stereo 3D molecular visualization on the desktop.
* '''[[#Passive_Stereo_3D|Passive Stereo 3D]]''' -- requires inexpensive lightweight polarized glasses. This is the standard solution for delivering stereo 3D to audiences of more than a small group of people.
* '''[[#Autostereoscopic_3D|Autostereoscopic 3D]]''' -- means that no glasses are required. However, current autostereoscopic displays tend do not to work well for molecular graphics due to their inability to faithfully represent fine detail such as thin bonds and wire meshes.

== Active Stereo 3D (High-Refresh) Displays ==

This solution would be analogous to using desktop CRT monitors with shutter glasses.

=== LCD Displays (120 Hz)===

* [http://us.acer.com/ac/en/US/content/model/ET.UG5HP.001 ACER GD235HZ]. 1920x1080 120Hz 2ms .

* [http://www.planar3d.com/3d-products/sa2311w/ Planar SA2311W]. This is a high-end 23" 3D-ready monitor. The resolution is 1900x1280 and has a 2ms refresh time. This worked well for us.

* [http://www.engadget.com/2008/08/26/viewsonic-shows-off-a-120hz-lcd-display-for-computers ViewSonic VX2265wm] (VX2268wm in Europe) - [http://www.google.com/products?q=ViewSonic%20VX2265wm&btnG=Search+Froogle&lmode=unknown On the market] and [http://sourceforge.net/mailarchive/forum.php?thread_name=DED5C399-7534-4D3D-8B19-E3676C4F1867%40weizmann.ac.il&forum_name=pymol-users verified working under FC 12]

* [http://www.nvidia.com/object/product_GeForce_3D_VisionBundle_us.html Samsung 2233RZ] - On the market. Quad buffered stereo in Linux works with a [http://en.wikipedia.org/wiki/Nvidia_Quadro G8x based graphics core] or better Quadro FX card with the 3 pin mini din stereo connector (currently, the cheapest card that works in Linux is the Quadro FX 3700), 195.22 (or newer) nvidia linux binary driver, and the Nvidia 3d vision kit. Even though the Quadro FX 1400/3450/4000 cards have a 3 pin stereo connector, these will not work with Nvidia 3D vision since these have core versions less than G8x. For more information see this forum post [http://forums.nvidia.com/index.php?showtopic=91072&view=findpost&p=968627 at the Nvidia Forums]. - SP

* USB only based stereo with the 3D vision kit works only in MS Windows (e.g. with a low end Quadro FX 370 that has no 3 pin mini din stereo connector). For more information see this forum post [http://forums.nvidia.com/index.php?showtopic=91072&view=findpost&p=968627 at the Nvidia Forums]. - SP

* The 195.22 Nvidia linux drivers do not support the Samsung 2233RZ in Stereo mode 3 or 10 for quad buffered stereo with other stereo kits, emitters, or goggles such as those purchased from NuVision, Stereographics, or Edimensional. You cannot use NuVision, Stereographics, or Edimensional goggles with the Nvidia 3D Vision emitters. - SP

* NVidia 3D NVision kit only supports DirectX software for GeForce (gaming cards) on Windows; users are reporting that they are not able to run PyMOL with NVision with these cards. Get a newer model low end quadro (> G8x graphics core) without the 3 pin mini din (e.g. Quadro 370) or with the 3 pin mini din (e.g. Quadro 3700) for Windows.

==== NVidia NVision 3D Setup ====
The NVidia 3D NVision setup provides a very nice 3D experience. You need the following to enable PyMOL to show NVision 3D on Windows. Please review the hardware and software requirements before moving on to the installation and setup.

=====Necessary Hardware=====
* Monitor: 120 Hz LCD: a [http://www.samsung.com/us/consumer/office/monitors/specialty/LS22CMFKFV/ZA/index.idx?pagetype=prd_detail&returnurl=|Samsung 2233RZ] or a [http://www.viewsonic.com/products/desktop-monitors/lcd/x-series/vx2265wm-fuhzion-lcd.htm|ViewSonic Fuhzion vx2265wm]
* Cable: [http://images.google.com/imgres?imgurl=http://www.logicsupply.com/images/dvi_connector_types.gif&imgrefurl=http://www.logicsupply.com/faq&usg=__G2BLaVTqBN4ie8fz_LJR1zc3zBc=&h=261&w=440&sz=15&hl=en&start=0&sig2=_hFM6ICIsxPq5WIAv8BCqg&zoom=1&tbnid=NIcKIs_BW_2rmM:&tbnh=135&tbnw=228&ei=KHN2TL-UC8P_lgfr44nsCw&prev=/images%3Fq%3Ddual%2Blink%2Bdvi%26hl%3Den%26biw%3D1475%26bih%3D1042%26gbv%3D2%26tbs%3Disch:1&itbs=1&iact=hc&vpx=136&vpy=323&dur=3153&hovh=173&hovw=292&tx=227&ty=74&oei=KHN2TL-UC8P_lgfr44nsCw&esq=1&page=1&ndsp=30&ved=1t:429,r:6,s:0 Dual Link DVI cable]; most 120Hz monitors will come with this cable--regardless, the cable is necessary
* Quadro Card: recent [http://www.nvidia.com/page/quadrofx_family.html Quadro] series graphics card (not a GeForce card) such as an FX 380 or 570 or later. The GeForce cards do not support windowed openGL stereo, so we do not support these series of cards for the NVision 3D solution. For linux, you must have a quadro card that has a 3 pin mini din connector. The cheapest/oldest card that will work with linux is the Quadro 3700.
** '''WARNING''': The Quadro FX1400 does not support 3d vision stereo on Windows7 or Linux.
* Emitter: [http://www.nvidia.com/object/3d-vision-main.html|GeForce 3D Vision] hardware kit (an emitter with 3D shutter glasses). For Linux, make sure your kit comes with the 3 pin mini din "VESA" to 2.5mm stereo cable to connect from the stereo output on the video card into the emitter.

=====Necessary Software=====
* Windows XP 32 bit (testing other OSs soon!), Windows Vista
* Latest Quadro [http://www.nvidia.com/Download/index.aspx?lang=en-us|Graphics Drivers from NVidia].
* Latest [http://www.nvidia.com/Download/index.aspx?lang=en-us|3D Graphics drivers for the NVision system]--under '''Product Type''' choose '''3D Vision'''.

=====Installation Instructions=====
======System Setup======
# Install the Quadro '''Graphics Drivers''' and reboot your machines
# Install the NVision Installation, hooking up the 3D emitter and glasses as directed in the instructions
## Make sure the 3D demos work
## Complete the '''3D Vision Drivers''' install (I had errors/warnings about old drivers but this did't matter)
# Specify how to drive the 3D by, click on
:::'''Windows Start Button''' > '''Control Panel''' > '''NVidia Control Panel''' > '''Manage 3D Settings''' (tab) > '''Global Settings''' (tab on the right) > '''Base Profile''' (tab). Then, under '''Settings''' choose '''Stereo - Display Mode'''. Next, select '''Generic Active Stereo (with NVidia IR Emitter)'''. If you have a DLP monitor/TV choose the corresponding DLP option. You '''must''' also set '''Stereo - Enable''' to '''on'''.

======Running PyMOL======
That's it! PyMOL should now work in Quad Buffered 3D Stereo using the NVidia 3D NVision system. To run PyMOL in 3D mode on:
*Windows
:: '''Start > PyMOL > PyMOL > PyMOL 3D Launch (last menu option) > PyMOL Stereo (Quad Buffered 3D)'''
*Linux
:: pymol -S -t 1
* Mac
:: Sorry, at this time the NVision system is not known to work on Macs.

=== DLP Projection Televisions ===

Projection televisions tend to be too large and fuzzy for desktop use. Also, a band of about 20 pixels around on the edge of the display are invisible, and this limitation cannot be eliminated through overscan since the image must be scanned at native resolution in order to support stereo 3D. The workaround is to shrink the PyMOL window to cover the visible portion of the screen. It is worth noting that true 3D-capable LCDs (as distinct from 3D-capable HDTVs) do not suffer from this problem.

Aside from the above concerns, the quality of the DLP stereo 3D effect is exceptional: there is absolutely no ghosting or cross-talk between the two images.

* [http://pages.samsung.com/us/dlp3d Samsung 3D-Ready DLP HDTVs] - work with PyMOL 1.2b3 & later without any special drivers. Quadro driver support is still lacking as of Feb. 1st, 2009 - WLD

* [http://www.mitsubishi-tv.com/ Mitsubishi 3D-Ready DLP HDTVs] - not yet tested, but are expected to work with PyMOL 1.2b3 & later without any special drivers. - WLD

See [http://www.3dmovielist.com/3dhdtvs.html The 3D HDTV List] for more 3D-capable HDTV options.

== Passive Stereo 3D Displays ==

=== One Piece Multi-layer LCD Displays ===

Affordable!

==== Zalman ====
'''iZ3D, the original supplier of Zalman display drivers has ceased operation and support as of 31 July 2012. DO NOT PURCHASE THESE MONITORS WITHOUT FURTHER CONFIRMATION of display support, the iZ3D support (required drivers, etc) is not activatable. If you do have further information, please post it here.''' [[User:Jedgold|Jedgold]] 12:21, 12 September 2012 (CDT)

* [http://www.zalman.co.kr/eng/product/Product_read.asp?Idx=219 Zalman 22-inch 3D LCD monitor] - works with PyMOL 1.2b3 & later without any special drivers. Great stereo quality provided that all drawn lines are at least 2 pixels thick. Menus are a bit awkward to use while in stereo mode, but even so, this 650 USD display provides excellent 3D molecular visualization in both full-screen in windowed modes. - WLD ('''The Zalman ZM-M220W is DeLano Scientific's RECOMMENDED SOLUTION as of Feb 11, 2009!''').
* [http://www.zalman.co.kr/Eng/product/Product_Read.asp?idx=391 Zalman 24-inch 3D LCD monitor] - also works with PyMOL 1.2b3 & later under LINUX (Centos 5 x86_64 plain kernel + NVidia driver from ELRepo). I'm using an NVidia Quadro FX 580 (G96GL) graphics card (£125). Monitor cost around £350. PyMOL automagically detects that quad buffered stereo is available on startup.--[[User:Bosmith|Bosmith]] 16:32, 2 December 2010 (UTC)
* [http://www.lg.com/us/computer-products/monitors/LG-led-monitor-D2342P-PN.jsp LG D2342P-PN]
===== On Linux =====
* setup by editing the xorg.conf file:
Option "Stereo" "7"

in the Screen section of xorg.conf and an additional:

Section "Extensions"
Option "Composite" "Disable"
EndSection

* launch using:
pymol -S -t 6

===== On Windows =====
# From the Start Menu: In the "PyMOL" folder, go into the "Stereo 3D Launch" subfolder, and select "PyMOL Zalman 3D (By Row)". You might want to control-drag a copy of that shortcut on to your desktop in order to drag & drop content files onto it for stereo 3D visualization
# From the Command Line:

"C:\Program Files\DeLano Scientific\PyMOL\PyMOLWin.exe" -S -t 6

===== On Mac =====
# MacPyMOL: Copy and rename the "MacPyMOL" application bundle to "MacPyMOLZalman". You can then double-click on the MacPyMOLZalman icon or drop data files directly onto it to visualize content in the Zalman stereo 3D mode.
# PyMOL X11 Hybrid Mode: Copy and rename the "MacPyMOL" appplication bundle to "PyMOLX11Zalman". After launching X11, you can then double-click on the PyMOLX11Zalman icon or drop data files directly onto it to visualize that content in the Zalman stereo 3D mode.

''For all platforms, remember to toggle stereo on and off using the "set stereo" command:''
set stereo, on

==== iZ3D ====
* [http://www.iz3d.com IZ3D] - works with PyMOL 1.2b3 & later without any special drivers. However, this display exhibits far too much cross-talk and interference between the two stereo images. Not suitable for professional use. - WLD

* IZ3D is closed as of 31 July 2012, and will not offer support to their products. [[User:Jedgold|Jedgold]] 12:26, 12 September 2012 (CDT)

=== Mirror-based Multi-LCD Solutions ===

Expensive!

* [http://www.planar3d.com Planar3D] "I have used these displays with nVidia Quadro graphics cards under both Windows and Linux running both PyMOL and Maestro. They work well, and the stereo quality is excellent!" - WLD.
* [http://www.inition.co.uk/inition/product.php?URL_=product_stereovis_omnia_mimo&SubCatID_=3 Omnia MIMO]

== Autostereoscopic LCD Displays ==

Some autostereoscopic displays have the ability to switch between 2D and 3D display modes. Others are built for 3D only.

* [http://www.dti3d.com Dimension Technologies Inc.]
* [http://www.seereal.com SeeReal Technologies]
* [http://www.newsight.com/3d-products/displays.html NewSight Corp.]

== Stereo 3D Projectors ==

Although these displays require shutter glasses out of the box, when combined with the adapters below and a special "silvered" screen, they can be used to project Passive Stereo 3D to a large audience.

=== Active Stereo 3D DLP Projectors ===

* [http://www.depthq.com DepthQ Stereoscopic] "The original DepthQ gave a very good stereo 3D effort with PyMOL, but I haven't seen their latest products." - WLD.
* [http://www.christiedigital.com/AMEN/Products/christieMirageS4K.htm Christie MIRAGE S+4K SXGA+ 6500 LUMEN DLP™ STEREOSCOPIC PROJECTOR] "I have been very impressed with the stereo 3D effect produced by MIRAGE projectors equipped with StereoGraphic ZScreens running PyMOL under Windows with a high-end nVidia Quadro card." - WLD.

=== Passive Stereo 3D Adaptor Hardware for Active Stereo 3D Projectors ===

These devices make it possible for a large audience to see projected stereo 3D using inexpensive polarized glasses.

* [http://reald-corporate.com/scientific/projectorzscreen.asp RealD StereoGraphics Projection ZScreen]

== Who Says What? ==

If you provide a specific quote or endorsement above, please say who you are so that everyone can know the source of the information.

* WLD = Warren L. DeLano of DeLano Scientific LLC
* SP = Sabuj Pattanayek of the Center For Structural Biology, Vanderbilt University

[[Category:Hardware_Options]]
[[Category:Stereo_3D_Display]]
[[Category:Stereo]]

Stereo 3D Display Options

2012-09-12T17:26:14Z

Jedgold: /* Zalman */

This page is for aggregating the latest know-how and links to current Stereo 3D display options best suited for molecular graphics applications like PyMOL. Please strive to provide objective factual information based on first-hand experiences while using the displays for real work and teaching.

Let's figure out together what stereo solutions work well in this brave new post-CRT world!

== Categories ==

* '''[[#Active_Stereo_3D|Active Stereo 3D]]''' -- requires expensive and/or bulky shutter glasses. For decades, this has been the standard solution for stereo 3D molecular visualization on the desktop.
* '''[[#Passive_Stereo_3D|Passive Stereo 3D]]''' -- requires inexpensive lightweight polarized glasses. This is the standard solution for delivering stereo 3D to audiences of more than a small group of people.
* '''[[#Autostereoscopic_3D|Autostereoscopic 3D]]''' -- means that no glasses are required. However, current autostereoscopic displays tend do not to work well for molecular graphics due to their inability to faithfully represent fine detail such as thin bonds and wire meshes.

== Active Stereo 3D (High-Refresh) Displays ==

This solution would be analogous to using desktop CRT monitors with shutter glasses.

=== LCD Displays (120 Hz)===

* [http://us.acer.com/ac/en/US/content/model/ET.UG5HP.001 ACER GD235HZ]. 1920x1080 120Hz 2ms .

* [http://www.planar3d.com/3d-products/sa2311w/ Planar SA2311W]. This is a high-end 23" 3D-ready monitor. The resolution is 1900x1280 and has a 2ms refresh time. This worked well for us.

* [http://www.engadget.com/2008/08/26/viewsonic-shows-off-a-120hz-lcd-display-for-computers ViewSonic VX2265wm] (VX2268wm in Europe) - [http://www.google.com/products?q=ViewSonic%20VX2265wm&btnG=Search+Froogle&lmode=unknown On the market] and [http://sourceforge.net/mailarchive/forum.php?thread_name=DED5C399-7534-4D3D-8B19-E3676C4F1867%40weizmann.ac.il&forum_name=pymol-users verified working under FC 12]

* [http://www.nvidia.com/object/product_GeForce_3D_VisionBundle_us.html Samsung 2233RZ] - On the market. Quad buffered stereo in Linux works with a [http://en.wikipedia.org/wiki/Nvidia_Quadro G8x based graphics core] or better Quadro FX card with the 3 pin mini din stereo connector (currently, the cheapest card that works in Linux is the Quadro FX 3700), 195.22 (or newer) nvidia linux binary driver, and the Nvidia 3d vision kit. Even though the Quadro FX 1400/3450/4000 cards have a 3 pin stereo connector, these will not work with Nvidia 3D vision since these have core versions less than G8x. For more information see this forum post [http://forums.nvidia.com/index.php?showtopic=91072&view=findpost&p=968627 at the Nvidia Forums]. - SP

* USB only based stereo with the 3D vision kit works only in MS Windows (e.g. with a low end Quadro FX 370 that has no 3 pin mini din stereo connector). For more information see this forum post [http://forums.nvidia.com/index.php?showtopic=91072&view=findpost&p=968627 at the Nvidia Forums]. - SP

* The 195.22 Nvidia linux drivers do not support the Samsung 2233RZ in Stereo mode 3 or 10 for quad buffered stereo with other stereo kits, emitters, or goggles such as those purchased from NuVision, Stereographics, or Edimensional. You cannot use NuVision, Stereographics, or Edimensional goggles with the Nvidia 3D Vision emitters. - SP

* NVidia 3D NVision kit only supports DirectX software for GeForce (gaming cards) on Windows; users are reporting that they are not able to run PyMOL with NVision with these cards. Get a newer model low end quadro (> G8x graphics core) without the 3 pin mini din (e.g. Quadro 370) or with the 3 pin mini din (e.g. Quadro 3700) for Windows.

==== NVidia NVision 3D Setup ====
The NVidia 3D NVision setup provides a very nice 3D experience. You need the following to enable PyMOL to show NVision 3D on Windows. Please review the hardware and software requirements before moving on to the installation and setup.

=====Necessary Hardware=====
* Monitor: 120 Hz LCD: a [http://www.samsung.com/us/consumer/office/monitors/specialty/LS22CMFKFV/ZA/index.idx?pagetype=prd_detail&returnurl=|Samsung 2233RZ] or a [http://www.viewsonic.com/products/desktop-monitors/lcd/x-series/vx2265wm-fuhzion-lcd.htm|ViewSonic Fuhzion vx2265wm]
* Cable: [http://images.google.com/imgres?imgurl=http://www.logicsupply.com/images/dvi_connector_types.gif&imgrefurl=http://www.logicsupply.com/faq&usg=__G2BLaVTqBN4ie8fz_LJR1zc3zBc=&h=261&w=440&sz=15&hl=en&start=0&sig2=_hFM6ICIsxPq5WIAv8BCqg&zoom=1&tbnid=NIcKIs_BW_2rmM:&tbnh=135&tbnw=228&ei=KHN2TL-UC8P_lgfr44nsCw&prev=/images%3Fq%3Ddual%2Blink%2Bdvi%26hl%3Den%26biw%3D1475%26bih%3D1042%26gbv%3D2%26tbs%3Disch:1&itbs=1&iact=hc&vpx=136&vpy=323&dur=3153&hovh=173&hovw=292&tx=227&ty=74&oei=KHN2TL-UC8P_lgfr44nsCw&esq=1&page=1&ndsp=30&ved=1t:429,r:6,s:0 Dual Link DVI cable]; most 120Hz monitors will come with this cable--regardless, the cable is necessary
* Quadro Card: recent [http://www.nvidia.com/page/quadrofx_family.html Quadro] series graphics card (not a GeForce card) such as an FX 380 or 570 or later. The GeForce cards do not support windowed openGL stereo, so we do not support these series of cards for the NVision 3D solution. For linux, you must have a quadro card that has a 3 pin mini din connector. The cheapest/oldest card that will work with linux is the Quadro 3700.
** '''WARNING''': The Quadro FX1400 does not support 3d vision stereo on Windows7 or Linux.
* Emitter: [http://www.nvidia.com/object/3d-vision-main.html|GeForce 3D Vision] hardware kit (an emitter with 3D shutter glasses). For Linux, make sure your kit comes with the 3 pin mini din "VESA" to 2.5mm stereo cable to connect from the stereo output on the video card into the emitter.

=====Necessary Software=====
* Windows XP 32 bit (testing other OSs soon!), Windows Vista
* Latest Quadro [http://www.nvidia.com/Download/index.aspx?lang=en-us|Graphics Drivers from NVidia].
* Latest [http://www.nvidia.com/Download/index.aspx?lang=en-us|3D Graphics drivers for the NVision system]--under '''Product Type''' choose '''3D Vision'''.

=====Installation Instructions=====
======System Setup======
# Install the Quadro '''Graphics Drivers''' and reboot your machines
# Install the NVision Installation, hooking up the 3D emitter and glasses as directed in the instructions
## Make sure the 3D demos work
## Complete the '''3D Vision Drivers''' install (I had errors/warnings about old drivers but this did't matter)
# Specify how to drive the 3D by, click on
:::'''Windows Start Button''' > '''Control Panel''' > '''NVidia Control Panel''' > '''Manage 3D Settings''' (tab) > '''Global Settings''' (tab on the right) > '''Base Profile''' (tab). Then, under '''Settings''' choose '''Stereo - Display Mode'''. Next, select '''Generic Active Stereo (with NVidia IR Emitter)'''. If you have a DLP monitor/TV choose the corresponding DLP option. You '''must''' also set '''Stereo - Enable''' to '''on'''.

======Running PyMOL======
That's it! PyMOL should now work in Quad Buffered 3D Stereo using the NVidia 3D NVision system. To run PyMOL in 3D mode on:
*Windows
:: '''Start > PyMOL > PyMOL > PyMOL 3D Launch (last menu option) > PyMOL Stereo (Quad Buffered 3D)'''
*Linux
:: pymol -S -t 1
* Mac
:: Sorry, at this time the NVision system is not known to work on Macs.

=== DLP Projection Televisions ===

Projection televisions tend to be too large and fuzzy for desktop use. Also, a band of about 20 pixels around on the edge of the display are invisible, and this limitation cannot be eliminated through overscan since the image must be scanned at native resolution in order to support stereo 3D. The workaround is to shrink the PyMOL window to cover the visible portion of the screen. It is worth noting that true 3D-capable LCDs (as distinct from 3D-capable HDTVs) do not suffer from this problem.

Aside from the above concerns, the quality of the DLP stereo 3D effect is exceptional: there is absolutely no ghosting or cross-talk between the two images.

* [http://pages.samsung.com/us/dlp3d Samsung 3D-Ready DLP HDTVs] - work with PyMOL 1.2b3 & later without any special drivers. Quadro driver support is still lacking as of Feb. 1st, 2009 - WLD

* [http://www.mitsubishi-tv.com/ Mitsubishi 3D-Ready DLP HDTVs] - not yet tested, but are expected to work with PyMOL 1.2b3 & later without any special drivers. - WLD

See [http://www.3dmovielist.com/3dhdtvs.html The 3D HDTV List] for more 3D-capable HDTV options.

== Passive Stereo 3D Displays ==

=== One Piece Multi-layer LCD Displays ===

Affordable!

==== Zalman ====
'''iZ3D, the original supplier of Zalman display drivers has ceased operation and support as of 31 July 2012. DO NOT PURCHASE THESE MONITORS WITHOUT FURTHER CONFIRMATION of display support, the iZ3D support (required drivers, etc) is not activatable. If you do have further information, please post it here.''' [[User:Jedgold|Jedgold]] 12:21, 12 September 2012 (CDT)

* [http://www.zalman.co.kr/eng/product/Product_read.asp?Idx=219 Zalman 22-inch 3D LCD monitor] - works with PyMOL 1.2b3 & later without any special drivers. Great stereo quality provided that all drawn lines are at least 2 pixels thick. Menus are a bit awkward to use while in stereo mode, but even so, this 650 USD display provides excellent 3D molecular visualization in both full-screen in windowed modes. - WLD ('''The Zalman ZM-M220W is DeLano Scientific's RECOMMENDED SOLUTION as of Feb 11, 2009!''').
* [http://www.zalman.co.kr/Eng/product/Product_Read.asp?idx=391 Zalman 24-inch 3D LCD monitor] - also works with PyMOL 1.2b3 & later under LINUX (Centos 5 x86_64 plain kernel + NVidia driver from ELRepo). I'm using an NVidia Quadro FX 580 (G96GL) graphics card (£125). Monitor cost around £350. PyMOL automagically detects that quad buffered stereo is available on startup.--[[User:Bosmith|Bosmith]] 16:32, 2 December 2010 (UTC)
* [http://www.lg.com/us/computer-products/monitors/LG-led-monitor-D2342P-PN.jsp LG D2342P-PN]
===== On Linux =====
* setup by editing the xorg.conf file:
Option "Stereo" "7"

in the Screen section of xorg.conf and an additional:

Section "Extensions"
Option "Composite" "Disable"
EndSection

* launch using:
pymol -S -t 6

===== On Windows =====
# From the Start Menu: In the "PyMOL" folder, go into the "Stereo 3D Launch" subfolder, and select "PyMOL Zalman 3D (By Row)". You might want to control-drag a copy of that shortcut on to your desktop in order to drag & drop content files onto it for stereo 3D visualization
# From the Command Line:

"C:\Program Files\DeLano Scientific\PyMOL\PyMOLWin.exe" -S -t 6

===== On Mac =====
# MacPyMOL: Copy and rename the "MacPyMOL" application bundle to "MacPyMOLZalman". You can then double-click on the MacPyMOLZalman icon or drop data files directly onto it to visualize content in the Zalman stereo 3D mode.
# PyMOL X11 Hybrid Mode: Copy and rename the "MacPyMOL" appplication bundle to "PyMOLX11Zalman". After launching X11, you can then double-click on the PyMOLX11Zalman icon or drop data files directly onto it to visualize that content in the Zalman stereo 3D mode.

''For all platforms, remember to toggle stereo on and off using the "set stereo" command:''
set stereo, on

==== iZ3D ====
* [http://www.iz3d.com IZ3D] - works with PyMOL 1.2b3 & later without any special drivers. However, this display exhibits far too much cross-talk and interference between the two stereo images. Not suitable for professional use. - WLD

=== Mirror-based Multi-LCD Solutions ===

Expensive!

* [http://www.planar3d.com Planar3D] "I have used these displays with nVidia Quadro graphics cards under both Windows and Linux running both PyMOL and Maestro. They work well, and the stereo quality is excellent!" - WLD.
* [http://www.inition.co.uk/inition/product.php?URL_=product_stereovis_omnia_mimo&SubCatID_=3 Omnia MIMO]

== Autostereoscopic LCD Displays ==

Some autostereoscopic displays have the ability to switch between 2D and 3D display modes. Others are built for 3D only.

* [http://www.dti3d.com Dimension Technologies Inc.]
* [http://www.seereal.com SeeReal Technologies]
* [http://www.newsight.com/3d-products/displays.html NewSight Corp.]

== Stereo 3D Projectors ==

Although these displays require shutter glasses out of the box, when combined with the adapters below and a special "silvered" screen, they can be used to project Passive Stereo 3D to a large audience.

=== Active Stereo 3D DLP Projectors ===

* [http://www.depthq.com DepthQ Stereoscopic] "The original DepthQ gave a very good stereo 3D effort with PyMOL, but I haven't seen their latest products." - WLD.
* [http://www.christiedigital.com/AMEN/Products/christieMirageS4K.htm Christie MIRAGE S+4K SXGA+ 6500 LUMEN DLP™ STEREOSCOPIC PROJECTOR] "I have been very impressed with the stereo 3D effect produced by MIRAGE projectors equipped with StereoGraphic ZScreens running PyMOL under Windows with a high-end nVidia Quadro card." - WLD.

=== Passive Stereo 3D Adaptor Hardware for Active Stereo 3D Projectors ===

These devices make it possible for a large audience to see projected stereo 3D using inexpensive polarized glasses.

* [http://reald-corporate.com/scientific/projectorzscreen.asp RealD StereoGraphics Projection ZScreen]

== Who Says What? ==

If you provide a specific quote or endorsement above, please say who you are so that everyone can know the source of the information.

* WLD = Warren L. DeLano of DeLano Scientific LLC
* SP = Sabuj Pattanayek of the Center For Structural Biology, Vanderbilt University

[[Category:Hardware_Options]]
[[Category:Stereo_3D_Display]]
[[Category:Stereo]]

Stereo 3D Display Options

2012-09-12T17:21:48Z

Jedgold: /* One Piece Multi-layer LCD Displays */

This page is for aggregating the latest know-how and links to current Stereo 3D display options best suited for molecular graphics applications like PyMOL. Please strive to provide objective factual information based on first-hand experiences while using the displays for real work and teaching.

Let's figure out together what stereo solutions work well in this brave new post-CRT world!

== Categories ==

* '''[[#Active_Stereo_3D|Active Stereo 3D]]''' -- requires expensive and/or bulky shutter glasses. For decades, this has been the standard solution for stereo 3D molecular visualization on the desktop.
* '''[[#Passive_Stereo_3D|Passive Stereo 3D]]''' -- requires inexpensive lightweight polarized glasses. This is the standard solution for delivering stereo 3D to audiences of more than a small group of people.
* '''[[#Autostereoscopic_3D|Autostereoscopic 3D]]''' -- means that no glasses are required. However, current autostereoscopic displays tend do not to work well for molecular graphics due to their inability to faithfully represent fine detail such as thin bonds and wire meshes.

== Active Stereo 3D (High-Refresh) Displays ==

This solution would be analogous to using desktop CRT monitors with shutter glasses.

=== LCD Displays (120 Hz)===

* [http://us.acer.com/ac/en/US/content/model/ET.UG5HP.001 ACER GD235HZ]. 1920x1080 120Hz 2ms .

* [http://www.planar3d.com/3d-products/sa2311w/ Planar SA2311W]. This is a high-end 23" 3D-ready monitor. The resolution is 1900x1280 and has a 2ms refresh time. This worked well for us.

* [http://www.engadget.com/2008/08/26/viewsonic-shows-off-a-120hz-lcd-display-for-computers ViewSonic VX2265wm] (VX2268wm in Europe) - [http://www.google.com/products?q=ViewSonic%20VX2265wm&btnG=Search+Froogle&lmode=unknown On the market] and [http://sourceforge.net/mailarchive/forum.php?thread_name=DED5C399-7534-4D3D-8B19-E3676C4F1867%40weizmann.ac.il&forum_name=pymol-users verified working under FC 12]

* [http://www.nvidia.com/object/product_GeForce_3D_VisionBundle_us.html Samsung 2233RZ] - On the market. Quad buffered stereo in Linux works with a [http://en.wikipedia.org/wiki/Nvidia_Quadro G8x based graphics core] or better Quadro FX card with the 3 pin mini din stereo connector (currently, the cheapest card that works in Linux is the Quadro FX 3700), 195.22 (or newer) nvidia linux binary driver, and the Nvidia 3d vision kit. Even though the Quadro FX 1400/3450/4000 cards have a 3 pin stereo connector, these will not work with Nvidia 3D vision since these have core versions less than G8x. For more information see this forum post [http://forums.nvidia.com/index.php?showtopic=91072&view=findpost&p=968627 at the Nvidia Forums]. - SP

* USB only based stereo with the 3D vision kit works only in MS Windows (e.g. with a low end Quadro FX 370 that has no 3 pin mini din stereo connector). For more information see this forum post [http://forums.nvidia.com/index.php?showtopic=91072&view=findpost&p=968627 at the Nvidia Forums]. - SP

* The 195.22 Nvidia linux drivers do not support the Samsung 2233RZ in Stereo mode 3 or 10 for quad buffered stereo with other stereo kits, emitters, or goggles such as those purchased from NuVision, Stereographics, or Edimensional. You cannot use NuVision, Stereographics, or Edimensional goggles with the Nvidia 3D Vision emitters. - SP

* NVidia 3D NVision kit only supports DirectX software for GeForce (gaming cards) on Windows; users are reporting that they are not able to run PyMOL with NVision with these cards. Get a newer model low end quadro (> G8x graphics core) without the 3 pin mini din (e.g. Quadro 370) or with the 3 pin mini din (e.g. Quadro 3700) for Windows.

==== NVidia NVision 3D Setup ====
The NVidia 3D NVision setup provides a very nice 3D experience. You need the following to enable PyMOL to show NVision 3D on Windows. Please review the hardware and software requirements before moving on to the installation and setup.

=====Necessary Hardware=====
* Monitor: 120 Hz LCD: a [http://www.samsung.com/us/consumer/office/monitors/specialty/LS22CMFKFV/ZA/index.idx?pagetype=prd_detail&returnurl=|Samsung 2233RZ] or a [http://www.viewsonic.com/products/desktop-monitors/lcd/x-series/vx2265wm-fuhzion-lcd.htm|ViewSonic Fuhzion vx2265wm]
* Cable: [http://images.google.com/imgres?imgurl=http://www.logicsupply.com/images/dvi_connector_types.gif&imgrefurl=http://www.logicsupply.com/faq&usg=__G2BLaVTqBN4ie8fz_LJR1zc3zBc=&h=261&w=440&sz=15&hl=en&start=0&sig2=_hFM6ICIsxPq5WIAv8BCqg&zoom=1&tbnid=NIcKIs_BW_2rmM:&tbnh=135&tbnw=228&ei=KHN2TL-UC8P_lgfr44nsCw&prev=/images%3Fq%3Ddual%2Blink%2Bdvi%26hl%3Den%26biw%3D1475%26bih%3D1042%26gbv%3D2%26tbs%3Disch:1&itbs=1&iact=hc&vpx=136&vpy=323&dur=3153&hovh=173&hovw=292&tx=227&ty=74&oei=KHN2TL-UC8P_lgfr44nsCw&esq=1&page=1&ndsp=30&ved=1t:429,r:6,s:0 Dual Link DVI cable]; most 120Hz monitors will come with this cable--regardless, the cable is necessary
* Quadro Card: recent [http://www.nvidia.com/page/quadrofx_family.html Quadro] series graphics card (not a GeForce card) such as an FX 380 or 570 or later. The GeForce cards do not support windowed openGL stereo, so we do not support these series of cards for the NVision 3D solution. For linux, you must have a quadro card that has a 3 pin mini din connector. The cheapest/oldest card that will work with linux is the Quadro 3700.
** '''WARNING''': The Quadro FX1400 does not support 3d vision stereo on Windows7 or Linux.
* Emitter: [http://www.nvidia.com/object/3d-vision-main.html|GeForce 3D Vision] hardware kit (an emitter with 3D shutter glasses). For Linux, make sure your kit comes with the 3 pin mini din "VESA" to 2.5mm stereo cable to connect from the stereo output on the video card into the emitter.

=====Necessary Software=====
* Windows XP 32 bit (testing other OSs soon!), Windows Vista
* Latest Quadro [http://www.nvidia.com/Download/index.aspx?lang=en-us|Graphics Drivers from NVidia].
* Latest [http://www.nvidia.com/Download/index.aspx?lang=en-us|3D Graphics drivers for the NVision system]--under '''Product Type''' choose '''3D Vision'''.

=====Installation Instructions=====
======System Setup======
# Install the Quadro '''Graphics Drivers''' and reboot your machines
# Install the NVision Installation, hooking up the 3D emitter and glasses as directed in the instructions
## Make sure the 3D demos work
## Complete the '''3D Vision Drivers''' install (I had errors/warnings about old drivers but this did't matter)
# Specify how to drive the 3D by, click on
:::'''Windows Start Button''' > '''Control Panel''' > '''NVidia Control Panel''' > '''Manage 3D Settings''' (tab) > '''Global Settings''' (tab on the right) > '''Base Profile''' (tab). Then, under '''Settings''' choose '''Stereo - Display Mode'''. Next, select '''Generic Active Stereo (with NVidia IR Emitter)'''. If you have a DLP monitor/TV choose the corresponding DLP option. You '''must''' also set '''Stereo - Enable''' to '''on'''.

======Running PyMOL======
That's it! PyMOL should now work in Quad Buffered 3D Stereo using the NVidia 3D NVision system. To run PyMOL in 3D mode on:
*Windows
:: '''Start > PyMOL > PyMOL > PyMOL 3D Launch (last menu option) > PyMOL Stereo (Quad Buffered 3D)'''
*Linux
:: pymol -S -t 1
* Mac
:: Sorry, at this time the NVision system is not known to work on Macs.

=== DLP Projection Televisions ===

Projection televisions tend to be too large and fuzzy for desktop use. Also, a band of about 20 pixels around on the edge of the display are invisible, and this limitation cannot be eliminated through overscan since the image must be scanned at native resolution in order to support stereo 3D. The workaround is to shrink the PyMOL window to cover the visible portion of the screen. It is worth noting that true 3D-capable LCDs (as distinct from 3D-capable HDTVs) do not suffer from this problem.

Aside from the above concerns, the quality of the DLP stereo 3D effect is exceptional: there is absolutely no ghosting or cross-talk between the two images.

* [http://pages.samsung.com/us/dlp3d Samsung 3D-Ready DLP HDTVs] - work with PyMOL 1.2b3 & later without any special drivers. Quadro driver support is still lacking as of Feb. 1st, 2009 - WLD

* [http://www.mitsubishi-tv.com/ Mitsubishi 3D-Ready DLP HDTVs] - not yet tested, but are expected to work with PyMOL 1.2b3 & later without any special drivers. - WLD

See [http://www.3dmovielist.com/3dhdtvs.html The 3D HDTV List] for more 3D-capable HDTV options.

== Passive Stereo 3D Displays ==

=== One Piece Multi-layer LCD Displays ===

Affordable!

==== Zalman ====
'''iZ3D, the maker of Zalman displays and (more importantly) Zalman display drivers has ceased operation and support as of 31 July 2012. DO NOT PURCHASE THESE MONITORS WITHOUT FURTHER CONFIRMATION, the support (required drivers, etc) do not appear to be activatable. If you do have further information, please post it here.''' [[User:Jedgold|Jedgold]] 12:21, 12 September 2012 (CDT)

* [http://www.zalman.co.kr/eng/product/Product_read.asp?Idx=219 Zalman 22-inch 3D LCD monitor] - works with PyMOL 1.2b3 & later without any special drivers. Great stereo quality provided that all drawn lines are at least 2 pixels thick. Menus are a bit awkward to use while in stereo mode, but even so, this 650 USD display provides excellent 3D molecular visualization in both full-screen in windowed modes. - WLD ('''The Zalman ZM-M220W is DeLano Scientific's RECOMMENDED SOLUTION as of Feb 11, 2009!''').
* [http://www.zalman.co.kr/Eng/product/Product_Read.asp?idx=391 Zalman 24-inch 3D LCD monitor] - also works with PyMOL 1.2b3 & later under LINUX (Centos 5 x86_64 plain kernel + NVidia driver from ELRepo). I'm using an NVidia Quadro FX 580 (G96GL) graphics card (£125). Monitor cost around £350. PyMOL automagically detects that quad buffered stereo is available on startup.--[[User:Bosmith|Bosmith]] 16:32, 2 December 2010 (UTC)
* [http://www.lg.com/us/computer-products/monitors/LG-led-monitor-D2342P-PN.jsp LG D2342P-PN]
===== On Linux =====
* setup by editing the xorg.conf file:
Option "Stereo" "7"

in the Screen section of xorg.conf and an additional:

Section "Extensions"
Option "Composite" "Disable"
EndSection

* launch using:
pymol -S -t 6

===== On Windows =====
# From the Start Menu: In the "PyMOL" folder, go into the "Stereo 3D Launch" subfolder, and select "PyMOL Zalman 3D (By Row)". You might want to control-drag a copy of that shortcut on to your desktop in order to drag & drop content files onto it for stereo 3D visualization
# From the Command Line:

"C:\Program Files\DeLano Scientific\PyMOL\PyMOLWin.exe" -S -t 6

===== On Mac =====
# MacPyMOL: Copy and rename the "MacPyMOL" application bundle to "MacPyMOLZalman". You can then double-click on the MacPyMOLZalman icon or drop data files directly onto it to visualize content in the Zalman stereo 3D mode.
# PyMOL X11 Hybrid Mode: Copy and rename the "MacPyMOL" appplication bundle to "PyMOLX11Zalman". After launching X11, you can then double-click on the PyMOLX11Zalman icon or drop data files directly onto it to visualize that content in the Zalman stereo 3D mode.

''For all platforms, remember to toggle stereo on and off using the "set stereo" command:''
set stereo, on

==== iZ3D ====
* [http://www.iz3d.com IZ3D] - works with PyMOL 1.2b3 & later without any special drivers. However, this display exhibits far too much cross-talk and interference between the two stereo images. Not suitable for professional use. - WLD

=== Mirror-based Multi-LCD Solutions ===

Expensive!

* [http://www.planar3d.com Planar3D] "I have used these displays with nVidia Quadro graphics cards under both Windows and Linux running both PyMOL and Maestro. They work well, and the stereo quality is excellent!" - WLD.
* [http://www.inition.co.uk/inition/product.php?URL_=product_stereovis_omnia_mimo&SubCatID_=3 Omnia MIMO]

== Autostereoscopic LCD Displays ==

Some autostereoscopic displays have the ability to switch between 2D and 3D display modes. Others are built for 3D only.

* [http://www.dti3d.com Dimension Technologies Inc.]
* [http://www.seereal.com SeeReal Technologies]
* [http://www.newsight.com/3d-products/displays.html NewSight Corp.]

== Stereo 3D Projectors ==

Although these displays require shutter glasses out of the box, when combined with the adapters below and a special "silvered" screen, they can be used to project Passive Stereo 3D to a large audience.

=== Active Stereo 3D DLP Projectors ===

* [http://www.depthq.com DepthQ Stereoscopic] "The original DepthQ gave a very good stereo 3D effort with PyMOL, but I haven't seen their latest products." - WLD.
* [http://www.christiedigital.com/AMEN/Products/christieMirageS4K.htm Christie MIRAGE S+4K SXGA+ 6500 LUMEN DLP™ STEREOSCOPIC PROJECTOR] "I have been very impressed with the stereo 3D effect produced by MIRAGE projectors equipped with StereoGraphic ZScreens running PyMOL under Windows with a high-end nVidia Quadro card." - WLD.

=== Passive Stereo 3D Adaptor Hardware for Active Stereo 3D Projectors ===

These devices make it possible for a large audience to see projected stereo 3D using inexpensive polarized glasses.

* [http://reald-corporate.com/scientific/projectorzscreen.asp RealD StereoGraphics Projection ZScreen]

== Who Says What? ==

If you provide a specific quote or endorsement above, please say who you are so that everyone can know the source of the information.

* WLD = Warren L. DeLano of DeLano Scientific LLC
* SP = Sabuj Pattanayek of the Center For Structural Biology, Vanderbilt University

[[Category:Hardware_Options]]
[[Category:Stereo_3D_Display]]
[[Category:Stereo]]

Plugins Tutorial

2012-04-23T14:20:34Z

Jedgold:

==Installing Plugins==
To install a plugin, simply save the plugin file and load it into PyMol with the ''Plugin -> Install Plugin...'' menu item. Alternatively, plugins can be installed by copying the file into the PYMOLPATH/module/pmg_tk/startup/ folder.

==Writing Plugins: Learn By Example==
This tutorial is a more sophisticated version of the [[PDB Loader Service]] plugin that is bundled with PyMol. It is a relatively simple plugin, but should prove to be a good starting point for developing new plugins.

===Registering your Plugin===
First you must add your plugin to the ''Plugins'' menu. This is most easily done in the ''__init__'' method of your plugin. A callback, fetchPDBDialog, is added. It is passed a reference to the main Tk app. It will need this in order to create new content in the main Tkinter loop. It is not strictly required in this example, but is needed in more complex interfaces.

<source lang="python">
def __init__(self):
self.menuBar.addmenuitem('Plugin', 'command',
'PDB Loader Service',
label = 'PDB Loader Service',
command = lambda s=self : fetchPDBDialog(s))
</source>

===Adding Functionality===
For this example we are going to dynamically download and load a pdb structure into the pymol interface. Here is a simple method which does that given a pdbCode.

<source lang="python">
def remote(pdbCode):
pdbCode = pdbCode.upper()
try:
pdbFile = urllib2.urlopen('http://www.rcsb.org/pdb/cgi/export.cgi/' +
pdbCode + '.pdb.gz?format=PDB&pdbId=' +
pdbCode + '&compression=gz')
cmd.read_pdbstr(zlib.decompress(pdbFile.read()[22:], -zlib.MAX_WBITS), pdbCode)
except:
print "Unexpected error:", sys.exc_info()[0]
tkMessageBox.showerror('Invalid Code',
'You entered an invalid pdb code:' + pdbCode)
</source>

===Creating the Interface===
Now we need to write the callback method, ''fetchPDBDialog'', which creates the interface.

<source lang="python">
def fetchPDBDialog(app):
pdbCode = tkSimpleDialog.askstring('PDB Loader Service',
'Please enter a 4-digit pdb code:',
parent=app.root)
remote(pdbCode)
</source>

Pretty simple! As of now you have a fully functional plugin that will prompt the user for a pdb code, download it from [http://www.rcsb.org/pdb/ RCSB], and load it into the PyMol interface.

===Extending Plugins to the Command Line===
Opening the dialog can be tedious, so let's add a command line callback to make use of this new functionality.

<source lang="python">
cmd.extend('remote', remote)
</source>

Now you can type ''remote 1di9'', for example, to load the the corresponding pdb.

==Full Source==
Here is the complete example. You can save this file and load it into PyMol with the ''Plugin -> Install Plugin...'' menu item. I also include the sample license that Warren provides for plugin developers. It is optional, of course.

<source lang="python">
# Copyright Notice
# ================
#
# The PyMOL Plugin source code in this file is copyrighted, but you can
# freely use and copy it as long as you don't change or remove any of
# the copyright notices.
#
# ----------------------------------------------------------------------
# This PyMOL Plugin is Copyright (C) 2004 by Charles Moad <cmoad@indiana.edu>
#
# All Rights Reserved
#
# Permission to use, copy, modify, distribute, and distribute modified
# versions of this software and its documentation for any purpose and
# without fee is hereby granted, provided that the above copyright
# notice appear in all copies and that both the copyright notice and
# this permission notice appear in supporting documentation, and that
# the name(s) of the author(s) not be used in advertising or publicity
# pertaining to distribution of the software without specific, written
# prior permission.
#
# THE AUTHOR(S) DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
# INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN
# NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
# CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
# USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
# OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
# PERFORMANCE OF THIS SOFTWARE.
# ----------------------------------------------------------------------

import tkSimpleDialog
import tkMessageBox
from pymol import cmd
import sys, urllib2, zlib

def __init__(self):
self.menuBar.addmenuitem('Plugin', 'command',
'PDB Loader Service',
label = 'PDB Loader Service',
command = lambda s=self : fetchPDBDialog(s))

def remote(pdbCode):
pdbCode = pdbCode.upper()
try:
pdbFile = urllib2.urlopen('http://www.rcsb.org/pdb/cgi/export.cgi/' +
pdbCode + '.pdb.gz?format=PDB&pdbId=' +
pdbCode + '&compression=gz')
cmd.read_pdbstr(zlib.decompress(pdbFile.read()[22:], -zlib.MAX_WBITS), pdbCode)
except:
print "Unexpected error:", sys.exc_info()[0]
tkMessageBox.showerror('Invalid Code',
'You entered an invalid pdb code:' + pdbCode)

def fetchPDBDialog(app):
pdbCode = tkSimpleDialog.askstring('PDB Loader Service',
'Please enter a 4-digit pdb code:',
parent=app.root)

remote(pdbCode)

cmd.extend('remote', remote)
</source>

[[Category:Developers|Plugins_Tutorial]]
[[Category:Plugins|Plugins_Tutorial]]
[[Category:Tutorials]]

CASTp

2010-11-10T20:56:13Z

Jedgold: /* Note*/

= Overview =
The CASTpyMOL plugin allows for the visualization of surfaces and voids identified from CASTp using pyMOL. For more information see the [http://sts-fw.bioengr.uic.edu/castp/pymol.php CASTp Website].

[[Category:Plugins]]

= Note =
As of 2010, the CASTpyMOL plugin does not appear to be supported by the CASTp group. The plugin is only available as a precompiled .pyc file compiled with an early version of python. Thus a 'bad magic number' error is encountered when attempting to initialize CASTpyMOL_V2
[[User:Jedgold|Jedgold]] 20:56, 10 November 2010 (UTC)

Ideas

2010-01-21T16:36:13Z

Jedgold: /* Low-Level Enhancement Ideas (Mostly C-oriented) */

=== Ideas for PyMOL Development ===

This page was originally developed for the 2008 Google Summer of Code competition, but seeing as PyMOL wasn't selected, this page can instead serve as a resource for ongoing PyMOL development efforts.

== Where to Start ==

Always start with Python and only delve down into the C code when absolutely necessary. Although PyMOL is mostly a C-based application, much of the that code is opaque, fragile, and unforgiving. Although C code refactoring is an important project goal, such work may not be ideal since once mistake could potentially to destabilize the entire platform.

Fortunately, the Python interpreter and the PyMOL command and selection languages make it possible to extend PyMOL safely and quickly. Even when performance is critical, Python should be the interface between external C, C++, and Java code and PyMOL's internal C data structures.

== Choosing a Topic ==

The best open-source code is usually written by an end-users attempting to meet their own pressing needs. So if you have already have a specific need which relates to PyMOL, then we strongly encourage you to follow up on that first!

If you are looking for ideas, then try to seek out enhancements and/or integrations that will impact the largest potential user base. For example, imagine what new things might be useful to virtually all medicinal chemists, all structural biologists, all movie-makers, all paper-writers, and so forth.

The ideas below are organized by category. Right now, integration with other open-source projects seems like the approach most likely to yield significant benefit, so those ideas are first.

== Integration Ideas (Linking Out to Useful Open-Source Tools) ==

In most cases, depending on the need, integration can be accomplished through standalone Python scripts, through new PyMOL commands, through PyMOL Wizards, or via Tkinter plugins.

* APBS (electrostatics calculations): Improve the existing plugin. Michael Lerner is currently leading this effort. See [[APBS]]
:: yea ([[User:Inchoate|Tree]] [[User:Jedgold|Jedgold]]) / nay (0)
* RDKit (cheminformatics, depiction, UFF cleanup, etc.): Lots of potential here, however C++ coding may be necessary for more advanced integration tasks. [http://www.rdkit.org RDKit home]
:: yea (0) / nay (0)
* GIMP (image manipulation): Streamline & document the process of exporting images from PyMOL into GIMP and preparing them for submission to scientific Journals.
:: yea (0) / nay (0)
* Jmol (publishing visualizations inside of web pages): Liason between PyMOL & Jmol projects to develop a shared molecular visualization data model compatible with both applications.
:: yea (0) / nay (0)
* Firefox (plugin): Develop an PyMOL plugin compatible with Firefox.
:: yea (0) / nay (0)
* MMTK (molecular mechanics -- Python/flexible): Develop the ability to round-trip molecular systems from PyMOL, into MMTK, and back.
:: yea (0) / nay (0)
* GROMACS (molecular mechanics -- C/fast) - Maybe some ideas can be shared with this guy. [http://www.kde-apps.org/content/show.php/Gromacs+GUI+?content=47665 Gromacs GUI]
:: yea ([[User:Jedgold|Jedgold]]) / nay (0)
* OpenOffice (escape Microsoft hegemony): Develop an PyMOL plugin.
:: yea (0) / nay (0)
* IPython integration (interactive shell): a robust alternative to the PyMOL command line?
:: yea (0) / nay (0)
* R (statistics): PyMOL a 3D viewer environment for visualizating & manipulating large statistical data sets?

Are there other key open-source packages we might specifically target for integration with PyMOL, either through GSoC or beyond?

== High-Level Enhancement Ideas (Mostly Python-oriented) ==

* Work on [[#More Ideas (Please add your own!)| MolViz]]
:: yea (0) / nay (0)
* Develop new plugins which automate routine tasks.
:: yea (0) / nay (0)
* Improve the Python API documentation.
:: yea (0) / nay (0)
* Flesh out the new "from pymol2 import PyMOL" instance-based PyMOL API.
:: yea (0) / nay (0)
* Develop alternate Tkinter "skins" (for custom OEM-like applications).
:: yea (0) / nay (0)
* Develop a Tkinter/TOGL widget which holds a PyMOL viewer instance.
:: yea (0) / nay (0)
* Develop a PyQt widget which holds a PyMOL viewer instance.
:: yea (0) / nay (0)
* Create a plugin-manager GUI in the style of Firefox, Rythmbox, Gedit, Eclipse. A GUI where it is easy to turn off/on plugins, configure them and see help-contents for them. Maybe also some way to paste a url to install a new Plugin.
:: yea (0) / nay (0)
* Add a plugin for a GUI window with the same functionality as the "Control Panel" window in SwissPDB Viewer.
:: yea (0) / nay (0)
* Extend and modify the PyMOL command language so as to be compatible with existing RasMol and/or Jmol scripts.
:: yea (0) / nay (0)
* Enhance the Mutagenesis Wizard in order to support Nucleic acids and/or Sugars.
:: yea (0) / nay (0)

== Low-Level Enhancement Ideas (Mostly C-oriented) ==

* Enable editing of displayed sequence alignments.
:: yea ([[User:Jedgold|Jedgold]]) / nay (0)
::: Would this then feed back to the structural alignment? [[User:Jedgold|Jedgold]]
* Add multi-line textual annotations
:: yea (0) / nay (0)
* Support additional annotation object including: arrow, lines, and blobs.
:: yea (0) / nay (0)
* Add display of secondary structure into the sequence viewer.
:: yea (0) / nay (0)
* Enable per-object Z clipping (especially in the ray tracer)
:: yea (0) / nay (0)
* Hilite H-bonds, salt bridges, Pi-stacking, Pi-cations, etc.
:: yea (0) / nay (0)
* Build in a simple forcefield and energy minimizer suitable for use with Mutagenesis.
:: yea (0) / nay (0)
* Incorporate a suite of standard NMR visualizations (restraint violations, per-residue RMS, etc.)
:: yea (0) / nay (0)
* Enumeration and display of low-energy conformers.
:: yea ([[User:Jedgold|Jedgold]]) / nay (0)
* Automated structure grafting (poor-man's homology modeling).
:: yea (0) / nay ([[User:Jedgold|Jedgold]])
::: Perhaps a plugin to Modeller instead? [[User:Jedgold|Jedgold]]
* Import of alignment files.
:: yea ([[User:Jedgold|Jedgold]]) / nay (0)
* Implement IMD (Interactive Molecular Dynamics) Interface, see http://www.ks.uiuc.edu/Research/vmd/imd/

== Difficult C-level Code Refactoring Ideas ==

* Assemble a test suite which thoroughly exercises the existing code (a prerequisite to major refactoring).
:: yea (0) / nay (0)
* Catch & handle memory-allocation failures gracefully (instead of crashing).
:: yea (0) / nay (0)
* Replace PyMOL's memory management & custom containers with a simple runtime object model.
:: yea (0) / nay (0)
* Separate the View and the Controllers from the Model so that they can all run asynchronously (on multiple cores).
:: yea (0) / nay (0)
* Enable generalized undo of changes made to the Model.
:: yea (0) / nay (0)
* Clean up the internal matrix handling code.
:: yea (0) / nay (0)

== Ideas Involving Proprietary APIs ==

Since these involve closed-source APIs and infrastructure, they aren't suitable for open-source development efforts. However, such requests are noted here for the sake of complete coverage.

* Create a Windows port with "native" look & feel. <- Could this be done in PyQT or PyGTK?. Then it would look "native", but be cross-platform and not proprietary.
:: yea (0) / nay (0)
* Integrate directly via Mathematica via MathLink.
:: yea (0) / nay (0)
* Further enhance JyMOL (Java-JNI/wrapped PyMOL)
:: yea ([[User:Inchoate|Tree]]) / nay (0)
* Integrate with Matlab.
:: yea (0) / nay (0)

== More Ideas (Please add your own!) ==
* [http://molviz.cs.toronto.edu/molviz MolViz] is a project to incorporate head tracking input into [http://pymol.sourceforge.net/ PyMol]. This is accomplished through a [[ImmersiveViz]] script written in Python to control the molecule's position using the existing [http://www.pymolwiki.org/index.php/Category:Commands PyMol API]. Related projects would include:
** Improving the existing [[ImmersiveViz]] PyMol plugin for more precise control of the environment.
** Developing new input drivers for the Wiimote form of control. This would require some bluetooth hacking.
** Implementing some other forms of input for head tracking, such as fisheye head tracking, IR webcam tracking, etc (refer to the end of this [[http://www.youtube.com/watch?v=ncShaY4VSac video]] for a better description).
:: yea (0) / nay (0)
* Provide a 2D chemical depiction of the current 3D view.
:: yea (0) / nay (0)
* Spreadsheet view with additional information (e.g. IC50's).
:: yea (0) / nay (0)
* Create additional documentation, screen casts, & tutorials.
:: yea (0) / nay (0)
* Export 3D PDF images.
:: yea (0) / nay (0)
* <strike>Add extra "Single Word Selectors" like "nucleic", "protein", "water", "ions", "backbone" (for nucleic acids or proteins), "mainchain", "sidechain"</strike>
:: yea (0) / nay (0)
* Add functionality that allows you to select atoms based on their location (i.e. select (x_coordinate < 10) and (z_coordinate > 0))
:: yea (0) / nay (0)
* set pdb_mirror option to use PDB mirrors other than RCSB for fetching structures (PDBe, PDBj); the EBI mirror is much faster from Europe for example.
:: yea (0) / nay (0)
* have the ability to link the TK console to the viewer so that users don't have to constantly alt+tab between what they want
:: yea (0) / nay (0)
* have the ability to disable typing in the viewer and automatically type in the TK console (I like being able to cut/paste/home/end)
:: yea (0) / nay (0)
* I see a lot of "can pymol do this" threads - any ideas of a good UI for a page of "things PyMOL can do?"
:: yea (0) / nay (0)
* make an option where I can turn on a coordinate grid - perhaps an object that is a cuboid grid around any object in the view so I can still alter how it's rendered?
:: yea (0) / nay (0)
* iPhone / Nexus One app(s)
:: yea (0) / nay (0)
* single-color bonds between nonidentical or any spherical atoms colored specifically
:: yea (0) / nay (0)
* double bonds as two parallel cylinders
:: yea (0) / nay (0)

Ideas

2010-01-21T16:34:00Z

Jedgold: /* Integration Ideas (Linking Out to Useful Open-Source Tools) */

=== Ideas for PyMOL Development ===

This page was originally developed for the 2008 Google Summer of Code competition, but seeing as PyMOL wasn't selected, this page can instead serve as a resource for ongoing PyMOL development efforts.

== Where to Start ==

Always start with Python and only delve down into the C code when absolutely necessary. Although PyMOL is mostly a C-based application, much of the that code is opaque, fragile, and unforgiving. Although C code refactoring is an important project goal, such work may not be ideal since once mistake could potentially to destabilize the entire platform.

Fortunately, the Python interpreter and the PyMOL command and selection languages make it possible to extend PyMOL safely and quickly. Even when performance is critical, Python should be the interface between external C, C++, and Java code and PyMOL's internal C data structures.

== Choosing a Topic ==

The best open-source code is usually written by an end-users attempting to meet their own pressing needs. So if you have already have a specific need which relates to PyMOL, then we strongly encourage you to follow up on that first!

If you are looking for ideas, then try to seek out enhancements and/or integrations that will impact the largest potential user base. For example, imagine what new things might be useful to virtually all medicinal chemists, all structural biologists, all movie-makers, all paper-writers, and so forth.

The ideas below are organized by category. Right now, integration with other open-source projects seems like the approach most likely to yield significant benefit, so those ideas are first.

== Integration Ideas (Linking Out to Useful Open-Source Tools) ==

In most cases, depending on the need, integration can be accomplished through standalone Python scripts, through new PyMOL commands, through PyMOL Wizards, or via Tkinter plugins.

* APBS (electrostatics calculations): Improve the existing plugin. Michael Lerner is currently leading this effort. See [[APBS]]
:: yea ([[User:Inchoate|Tree]] [[User:Jedgold|Jedgold]]) / nay (0)
* RDKit (cheminformatics, depiction, UFF cleanup, etc.): Lots of potential here, however C++ coding may be necessary for more advanced integration tasks. [http://www.rdkit.org RDKit home]
:: yea (0) / nay (0)
* GIMP (image manipulation): Streamline & document the process of exporting images from PyMOL into GIMP and preparing them for submission to scientific Journals.
:: yea (0) / nay (0)
* Jmol (publishing visualizations inside of web pages): Liason between PyMOL & Jmol projects to develop a shared molecular visualization data model compatible with both applications.
:: yea (0) / nay (0)
* Firefox (plugin): Develop an PyMOL plugin compatible with Firefox.
:: yea (0) / nay (0)
* MMTK (molecular mechanics -- Python/flexible): Develop the ability to round-trip molecular systems from PyMOL, into MMTK, and back.
:: yea (0) / nay (0)
* GROMACS (molecular mechanics -- C/fast) - Maybe some ideas can be shared with this guy. [http://www.kde-apps.org/content/show.php/Gromacs+GUI+?content=47665 Gromacs GUI]
:: yea ([[User:Jedgold|Jedgold]]) / nay (0)
* OpenOffice (escape Microsoft hegemony): Develop an PyMOL plugin.
:: yea (0) / nay (0)
* IPython integration (interactive shell): a robust alternative to the PyMOL command line?
:: yea (0) / nay (0)
* R (statistics): PyMOL a 3D viewer environment for visualizating & manipulating large statistical data sets?

Are there other key open-source packages we might specifically target for integration with PyMOL, either through GSoC or beyond?

== High-Level Enhancement Ideas (Mostly Python-oriented) ==

* Work on [[#More Ideas (Please add your own!)| MolViz]]
:: yea (0) / nay (0)
* Develop new plugins which automate routine tasks.
:: yea (0) / nay (0)
* Improve the Python API documentation.
:: yea (0) / nay (0)
* Flesh out the new "from pymol2 import PyMOL" instance-based PyMOL API.
:: yea (0) / nay (0)
* Develop alternate Tkinter "skins" (for custom OEM-like applications).
:: yea (0) / nay (0)
* Develop a Tkinter/TOGL widget which holds a PyMOL viewer instance.
:: yea (0) / nay (0)
* Develop a PyQt widget which holds a PyMOL viewer instance.
:: yea (0) / nay (0)
* Create a plugin-manager GUI in the style of Firefox, Rythmbox, Gedit, Eclipse. A GUI where it is easy to turn off/on plugins, configure them and see help-contents for them. Maybe also some way to paste a url to install a new Plugin.
:: yea (0) / nay (0)
* Add a plugin for a GUI window with the same functionality as the "Control Panel" window in SwissPDB Viewer.
:: yea (0) / nay (0)
* Extend and modify the PyMOL command language so as to be compatible with existing RasMol and/or Jmol scripts.
:: yea (0) / nay (0)
* Enhance the Mutagenesis Wizard in order to support Nucleic acids and/or Sugars.
:: yea (0) / nay (0)

== Low-Level Enhancement Ideas (Mostly C-oriented) ==

* Enable editing of displayed sequence alignments.
:: yea (0) / nay (0)
* Add multi-line textual annotations
:: yea (0) / nay (0)
* Support additional annotation object including: arrow, lines, and blobs.
:: yea (0) / nay (0)
* Add display of secondary structure into the sequence viewer.
:: yea (0) / nay (0)
* Enable per-object Z clipping (especially in the ray tracer)
:: yea (0) / nay (0)
* Hilite H-bonds, salt bridges, Pi-stacking, Pi-cations, etc.
:: yea (0) / nay (0)
* Build in a simple forcefield and energy minimizer suitable for use with Mutagenesis.
:: yea (0) / nay (0)
* Incorporate a suite of standard NMR visualizations (restraint violations, per-residue RMS, etc.)
:: yea (0) / nay (0)
* Enumeration and display of low-energy conformers.
:: yea (0) / nay (0)
* Automated structure grafting (poor-man's homology modeling).
:: yea (0) / nay (0)
* Import of alignment files.
:: yea (0) / nay (0)
* Implement IMD (Interactive Molecular Dynamics) Interface, see http://www.ks.uiuc.edu/Research/vmd/imd/

== Difficult C-level Code Refactoring Ideas ==

* Assemble a test suite which thoroughly exercises the existing code (a prerequisite to major refactoring).
:: yea (0) / nay (0)
* Catch & handle memory-allocation failures gracefully (instead of crashing).
:: yea (0) / nay (0)
* Replace PyMOL's memory management & custom containers with a simple runtime object model.
:: yea (0) / nay (0)
* Separate the View and the Controllers from the Model so that they can all run asynchronously (on multiple cores).
:: yea (0) / nay (0)
* Enable generalized undo of changes made to the Model.
:: yea (0) / nay (0)
* Clean up the internal matrix handling code.
:: yea (0) / nay (0)

== Ideas Involving Proprietary APIs ==

Since these involve closed-source APIs and infrastructure, they aren't suitable for open-source development efforts. However, such requests are noted here for the sake of complete coverage.

* Create a Windows port with "native" look & feel. <- Could this be done in PyQT or PyGTK?. Then it would look "native", but be cross-platform and not proprietary.
:: yea (0) / nay (0)
* Integrate directly via Mathematica via MathLink.
:: yea (0) / nay (0)
* Further enhance JyMOL (Java-JNI/wrapped PyMOL)
:: yea ([[User:Inchoate|Tree]]) / nay (0)
* Integrate with Matlab.
:: yea (0) / nay (0)

== More Ideas (Please add your own!) ==
* [http://molviz.cs.toronto.edu/molviz MolViz] is a project to incorporate head tracking input into [http://pymol.sourceforge.net/ PyMol]. This is accomplished through a [[ImmersiveViz]] script written in Python to control the molecule's position using the existing [http://www.pymolwiki.org/index.php/Category:Commands PyMol API]. Related projects would include:
** Improving the existing [[ImmersiveViz]] PyMol plugin for more precise control of the environment.
** Developing new input drivers for the Wiimote form of control. This would require some bluetooth hacking.
** Implementing some other forms of input for head tracking, such as fisheye head tracking, IR webcam tracking, etc (refer to the end of this [[http://www.youtube.com/watch?v=ncShaY4VSac video]] for a better description).
:: yea (0) / nay (0)
* Provide a 2D chemical depiction of the current 3D view.
:: yea (0) / nay (0)
* Spreadsheet view with additional information (e.g. IC50's).
:: yea (0) / nay (0)
* Create additional documentation, screen casts, & tutorials.
:: yea (0) / nay (0)
* Export 3D PDF images.
:: yea (0) / nay (0)
* <strike>Add extra "Single Word Selectors" like "nucleic", "protein", "water", "ions", "backbone" (for nucleic acids or proteins), "mainchain", "sidechain"</strike>
:: yea (0) / nay (0)
* Add functionality that allows you to select atoms based on their location (i.e. select (x_coordinate < 10) and (z_coordinate > 0))
:: yea (0) / nay (0)
* set pdb_mirror option to use PDB mirrors other than RCSB for fetching structures (PDBe, PDBj); the EBI mirror is much faster from Europe for example.
:: yea (0) / nay (0)
* have the ability to link the TK console to the viewer so that users don't have to constantly alt+tab between what they want
:: yea (0) / nay (0)
* have the ability to disable typing in the viewer and automatically type in the TK console (I like being able to cut/paste/home/end)
:: yea (0) / nay (0)
* I see a lot of "can pymol do this" threads - any ideas of a good UI for a page of "things PyMOL can do?"
:: yea (0) / nay (0)
* make an option where I can turn on a coordinate grid - perhaps an object that is a cuboid grid around any object in the view so I can still alter how it's rendered?
:: yea (0) / nay (0)
* iPhone / Nexus One app(s)
:: yea (0) / nay (0)
* single-color bonds between nonidentical or any spherical atoms colored specifically
:: yea (0) / nay (0)
* double bonds as two parallel cylinders
:: yea (0) / nay (0)

Cealign plugin

2009-07-17T17:43:42Z

Jedgold: /* Requirements */

== Introduction ==

'''Go directly to [[Cealign#Version_0.8-RBS|DOWNLOAD]]'''

This page is the home page of the open-source CEAlign PyMOL plugin. The CE algorithm is a fast and accurate protein structure alignment algorithm, pioneered by Drs. Shindyalov and Bourne (See
References). There are a few changes from the original CE publication (See Notes).

The source code is implemented in C with the rotations finally done by Numpy in Python. Because the computationally complex portion of the code is written in C, it's quick. That is, on my machines --- relatively fast 64-bit machines --- I can align two 400+ amino acid structures in about 0.300 s with the C++ implementation.

This plugs into PyMol very easily. See [[Cealign#The_Code|the code]] and [[Cealign#Examples|examples]] for installation and usage.

== Comparison to PyMol ==
'''Why should you use this?'''

PyMOL's structure alignment algorithm is fast and robust. However, its first step is to perform a sequence alignment of the two selections. Thus, proteins in the '''twilight zone''' or those having a low sequence identity, may not align well. Because CE is a structure-based alignment, this is not a problem. Consider the following example. The image at LEFT was the result of CE-aligning two proteins (1C0M chain B to 1BCO). The result is '''152''' aligned (alpha carbons) residues (not atoms) at '''4.96 Angstroms'''. The image on the RIGHT shows the results from PyMol's align command: an alignment of '''221 atoms''' (not residues) at an RMSD of '''15.7 Angstroms'''.

<gallery>
Image:cealign_ex1.png|Cealign's results (152 aligned; 4.96 Ang.)
Image:pymol_align.png|PyMol's results (763 atoms; 18.4 Ang. )
</gallery>

=== Fit vs. optAlign ===
====Take Home messages====
* [[fit]] and [[optAlign]] perform nearly equally as well
* if you need an algorithm with an appropriate reference, use [[optAlign]] (references at bottom of page).
* [[fit]] is faster -- if you're aligning many structures, use it over [[optAlign]]

====Discussion====
[[optAlign]] is a function within the [[Cealign]] package that performs the optimal superposition of two objects of equal length. [[optAlign]] follows the Kabsch algorithm which is a closed form, and provably optimal solution to the problem. [[fit]] on the other hand uses the Jacobi rotations to iteratively arrive at the solution of optimal superposition. The difference in error between [[optAilgn]] and [[fit]] seems to be a non-issue (see below) as they both arrive at equivalent solutions for the rotation matrix. The two algorithms are undertake different approaches to orthogonally diagonalizing the correlation matrix.

PyMOL's [[fit]] is fast and works well. If you have to use something with a known reference then check out the "optAlign" function from the qkabsch.py file that comes with this [[Calign]] package. If not, you can just use [[fit]] and avoid installing new software. :-)

optAlign is slower than fit. I just tested both on a sample NMR ensemble; and, while not an extensive validation of "fit" it shows that (1) fit is faster; and (2) fit gets the same exact RMSD as "optAlign" (when optAlign is told to use all atoms, not just CA). To make optAlign use all atoms and not just the alpha-carbon backbones, comment out (that is, put a "#" at the start of lines 183 and 184 in qkabsch.py, where it says "CUT HERE").

<source lang="python">
fetch 1nmr
split_states 1nmr
delete 1nmr

# compare fit and optAlign RMSDs
for x in cmd.get_names(): print cmd.fit("1nmr_0001", x)
for x in cmd.get_names(): optAlign(x, "1nmr_0001")
</source>
<source lang="bash">
# results from fit
0.0
4.50344991684
5.33588504791
5.78613853455
7.25597000122
6.67145586014
3.25131297112
3.36766290665
6.74802017212
5.1579709053
5.96959495544
6.68093347549
4.13217163086
5.51539039612
6.24266338348
6.03838825226
5.01363992691
5.33336305618
6.87617444992
7.797062397

#results from optAlign
RMSD=0.000000
RMSD=4.503450
RMSD=5.335886
RMSD=5.786138
RMSD=7.255970
RMSD=6.671456
RMSD=3.251313
RMSD=3.367663
RMSD=6.748021
RMSD=5.157971
RMSD=5.969595
RMSD=6.680934
RMSD=4.132172
RMSD=5.515390
RMSD=6.242664
RMSD=6.038388
RMSD=5.013640
RMSD=5.333363
RMSD=6.876174
RMSD=7.797062
</source>

== Examples ==
=== Usage ===
==== Syntax ====

CEAlign has the semantic, and syntactic formalism of
<source lang="python">
cealign MASTER, TARGET
</source>
where a post-condition of the algorithm is that the coordinates of the '''MASTER''' protein are unchanged. This allows for easier multi-protein alignments. For example,
<source lang="python">
cealign 1AUE, 1BZ4
cealign 1AUE, 1B68
cealign 1AUE, 1A7V
cealign 1AUE, 1CPR
</source>
will superimpose all the TARGETS onto the MASTER.

=====Examples=====
<source lang="python">
cealign 1cll and i. 42-55, 1ggz and c. A
cealign 1kao, 1ctq
cealign 1fao, 1eaz
</source>

=====Multiple Structure Alignments=====
Use the '''alignto''' command, now provided with cealign. Just type,
<source lang="python">
alignto PROT
</source>
to align all your proteins in PyMOL to the one called, '''PROT'''.

=== Results ===
See '''Changes''' for updates. But, overall, the results here are great.

<gallery>
Image:v7_1fao_1eaz.png|EASY: 1FAO vs. 1EAZ; 96 residues, 1.28 Ang
Image:v7_1cbs_1hmt.png|EASY: 1CBS vs. 1HMT; 128 residues, 2.01 Ang
Image:v7_1a15_1b50.png|MODERATE: 1A15 vs 1B50; 56 residues, 2.54 Ang.
Image:v7_1oan_1s6n.png|EASY: 1OAN vs. 1S6N (state 1); 96 residues aligned to 3.83 Ang. RMSD.
Image:v7_1rlw_1byn.png|HARD: 1RLW to 1BYN; 104 residues; 2.21 Ang.
Image:v7_1ten_3hhr.png|HARD: 1TEN vs. 3HHR; 80 residues, 2.91 Ang.
Image:v7_2sim_1nsb.png|HARD: 2SIM vs. 1NSB; 272 residues, 4.93 Ang.
Image:v7_1cew_1mol.png|HARD: 1CEW vs. 1MOL; 80 residues, 4.03 Ang.
</gallery>

== Installation ==

===Mac OS X (10.5)===
[[Image:Cealign mac os x.png|300px|thumb|center|CEAlign running on Mac OS X (10.5)]]
* Install PyMOL under fink.
* Install Numpy for fink:
<source lang="bash">
/sw/bin/fink install scipy-core-py25
</source>
* Download and install cealign (download instructions below)
<source lang="bash">
sudo /sw/bin/python setup.py install
</source>
* In PyMOL, run the two scripts needed for cealing: "cealign.py" and "qkabsch.py". These are located in the cealign directory you previously downloaded.
* Voila!
* Note that the above python version must match the same version that is used by PyMOL. If you are using the pre-compiled version of MacPyMOL, the above instructions won't work.

===Windows systems===
====CEAlign 0.9====
This is a Win32 build of CEAlign 0.9 [http://pymolwiki.org/index.php/Cealign#Beta_Version_0.9]
=====Requirements=====
* Christoph Gohlke's latest '''unofficial''' PyMol build: http://www.lfd.uci.edu/~gohlke/#pythonlibs
* "Python 2.6.2 Windows installer" from python.org: http://www.python.org/download/
* '''CEAlign09Win32.zip''' from: http://users.umassmed.edu/shivender.shandilya/pymol/CEAlign09Win32.zip
=====Directions=====
# Download the '''CEAlign09Win32.zip''' file
# Unzip the downloaded file and follow the directions as per the included README.txt
# Enjoy the ''awesomeness'' that is CEAlign!
====CEAlign 0.8====
This is a quick and dirty method to use CEAlign 0.8 on Win32 system with the '''official''' Pymol builds...
=====Requirements=====
* Latest PyMol, installed on your system
* Numpy for python 2.4 -- quick download of just what's needed: http://users.umassmed.edu/shivender.shandilya/pymol/cealign08/numpy.zip
[Note: If this file is corrupt, you may download the latest 'Numpy for Python 2.4' directly from SourceForge.net
* Pre-compiled ccealign.pyd python module: http://users.umassmed.edu/Shivender.Shandilya/pymol/cealign08/ccealign.zip
* Modified pymolrc: http://users.umassmed.edu/Shivender.Shandilya/pymol/cealign08/pymolrc
* cealign.py and qkabsch.py from the Cealign-0.8-RBS package: download below

=====Directions=====
# Unzip the numpy.zip file, which will give you a folder named '''numpy'''
# Move this entire folder to: C:\Program Files\DeLano Scientific\PyMOL\modules\ (or the corresponding location on your system)
# Unzip ccealign.zip, which will give you a file called '''ccealign.pyd'''
# Move this pyd file to: C:\Program Files\DeLano Scientific\PyMOL\py24\DLLs\ (or the corresponding location on your system)
# Copy the downloaded '''pymolrc''' file to: C:\Program Files\DeLano Scientific\PyMOL\ (or the corresponding location on your system)
# Extract and copy the files cealign.py and qkabsch.py from the Cealign-0.8-RBS package to: C:\Program Files\DeLano Scientific\PyMOL\py24\Lib\ (or the corresponding location on your system)
# Run PyMol and load some molecules
# Run this command in Pymol: '''cealign molecule1, molecule2'''
# Enjoy!

===Gentoo Linux===
Add the science overlay via
layman -a sci
and emerge the cealign plugin
emerge pymol-plugins-cealign

===*nix systems===
====Requirements====
* C compiler
* Python 2.4+ with distutils
* Numpy
** for User-compiled PyMOL: <source lang="python">python setup.py install</source>
** for the precompiled version of PyMOL <source lang="python">python setup.py install --prefix "" --root /DIR_TO/pymol/ext/</source>

====Directions====
# uncompress the distribution file '''cealign-VERSION.tgz'''
# cd cealign-VERSION
# sudo python setup.py install # if you installed by PyMOL by hand
## python setup.py install --prefix "" --root /DIR/TO/pymol/ext/ # if you are using the precompiled binary download
# insert "run DIR_TO_CEALIGN/cealign.py" and "run DIR_TO_CEALIGN/qkabsch.py" into your '''.pymolrc''' file, or just run the two Python scripts by hand.
# load some molecules
# run, '''cealign molecule1, molecule2'''
# enjoy

=====Pre-compiled Hackish Install=====
For those people that prefer to use the pre-compiled version of PyMOL, here are the basics for your install. '''This is a poor method of installing Cealign. I suggest users compile and install their own PyMOL.''' The final goal is to get
# '''ccealign.so''' module into '''PYMOL/ext/lib/python2.4/site-packages'''
# numpy installed (get the numpy directory into (or linked into) '''PYMOL/ext/lib/python2.4/site-packages'''
# and be able to run cealign.py and qkabsch.py from PyMOL.
If you can do the above three steps, '''cealign''' should run from the pre-compiled PyMOL.

In more detail, on a completely fictitious machine --- that is, I created the following commands from a fake machine and I don't expect a copy/paste of this to work '''anywhere''', but the commands should be helpful enough to those who need it:
<source lang="python">
# NOTES:
# This is fake code: don't copy/paste it.
#
# PYMOL='dir to precompiled PyMOL install'
# CEALIGN='dir where you will unpack cealign'
# replace lib with lib64 for x86-64
# install numpy
apt-get install numpy

# link numpy to PyMOL
ln -s /usr/local/lib/python2.4/site-packages/numpy PYMOL/ext/lib/python2.4/site-packages

# download and install Cealign
wget http://www.pymolwiki.org/images/e/ed/Cealign-0.6.tar.bz2
tar -jxvf Cealign-0.6.tar.bz2
cd cealign-0.6
sudo python setup.py build
cp build/lib-XYZ-linux/ccealign.so PYMOL/ext/lib/python2.4/site-packages

# run pymol and try it out
pymol
run CEALIGN/cealign.py
run CEALIGN/qkabsch.py
fetch 1cew 1mol, async=0
cealign 1c, 1m
</source>

== The Code ==
Please unpack and read the documentation. All comments/questions should be directed to Jason Vertrees (javertre _at_ utmb ...dot... edu).

'''LATEST IS v0.8-RBS'''. (Dedicated to Bryan Sutton for allowing me to use his computer for testing.)

=== Version 0.8-RBS ===
* '''Download: [[Media:Cealign-0.8-RBS.tar.bz2|CE Align v0.8-RBS]] (bz2)'''
* '''Download: [[Media:Cealign-0.8-RBS.zip|CE Align v0.8-RBS]] (zip)'''

=== Beta Version 0.9 ===
Use at your own peril. Please report any problems or inconsistent alignments to this discussion page, or to me directly; my email address all over this page.

'''Improvements/Changes''':
* All C++
** So, faster
** comes with the dependencies built in
* No numpy

''' Download: [[Media:Cealign-0.9.zip|CE Align v0.9]] (zip)'''

== Coming Soon ==
* Windows binary
* Linux Binaries (32bit, x86-64)
* Better instructions for precompiled distributions
* Optimization

== Updates ==

=== 2008-03-25 ===
Pure C++ code released. See the beta version above.

=== 2007-04-14 ===
v0.8-RBS source updated. Found the bug that had been plaguing 32-bit machines. This should be the last release for a little while.

Also, I provide the option of aligning based solely upon RMSD or upon the better CE-Score. See the '''References''' for information on the '''CE Score'''.

== Troubleshooting ==

Post your problems/solutions here.

=== Unicode Issues in Python/Numpy ===
'''Problem''': Running/Installing cealign gives
<source lang="python">
Traceback (most recent call last):
File "/home/byron/software/pymol_1.00b17/pymol/modules/pymol/parser.py",
line 308, in parse
File "/home/byron/software/pymol_1.00b17/pymol/modules/pymol/parsing.py",
line 410, in run_file
File "qkabsch.py", line 86, in ?
import numpy
File "/usr/lib/python2.4/site-packages/numpy/__init__.py", line 36, in ?
import core
File "/usr/lib/python2.4/site-packages/numpy/core/__init__.py", line 5, in ?
import multiarray
ImportError: /home/byron/software/pymol/ext/lib/python2.4/site-packages/numpy/core/multiarray.so:
undefined symbol: _PyUnicodeUCS4_IsWhitespace
</source>
where the important line is
<source lang="python">
undefined symbol: _PyUnicodeUCS4_IsWhitespace
</source>

This problem indicates that your Numpy Unicode is using a different byte-size for unicode characters than is the Python distribution your PyMOL is running from. For example, this can happen if you use the pre-built PyMOL and some other pre-built Numpy package.

'''Solution''': Hand-install Numpy.

=== LinAlg Module Not Found ===
'''Problem''': Running CE Align gives the following error message:
<source lang="python">
run qkabsch.py
Traceback (most recent call last):
File "/usr/lib/python2.4/site-packages/pymol/parser.py", line 285, in parse
parsing.run_file(exp_path(args[nest][0]),pymol_names,pymol_names)
File "/usr/lib/python2.4/site-packages/pymol/parsing.py", line 407, in run_file
execfile(file,global_ns,local_ns)
File "qkabsch.py", line 86, in ?
import numpy
File "/usr/lib/python2.4/site-packages/numpy/__init__.py", line 40, in ?
import linalg
ImportError: No module named linalg
</source>

'''Solution''': You do not have the linear algebra module installed (or Python can't find it) on your machine. One workaround is to install [http://www.scipy.org/ Scientific Python]. (on debian/ubuntu this can be done by: sudo apt-get install python-scipy) Another is to reinstall the Numpy package from source, ensuring that you have the necessary requirements for the linear algebra module (linpack, lapack, fft, etc.).

=== CCEAlign & NumPy Modules Not Found ===
'''Problem''': Running CE Align gives the following error message:
<source lang="python">
PyMOL>run cealign.py
Traceback (most recent call last):
File "/home/local/warren/MacPyMOL060530/build/Deployment/MacPyMOL.app/pymol/modules/pymol/parser.py", line 297, in parse
File "/home/local/warren/MacPyMOL060530/build/Deployment/MacPyMOL.app/pymol/modules/pymol/parsing.py", line 408, in run_file
File "/usr/local/pymol/scripts/cealign-0.1/cealign.py", line 59, in ?
from ccealign import ccealign
ImportError: No module named ccealign
run qkabsch.py
Traceback (most recent call last):
File "/home/local/warren/MacPyMOL060530/build/Deployment/MacPyMOL.app/pymol/modules/pymol/parser.py", line 297, in parse
File "/home/local/warren/MacPyMOL060530/build/Deployment/MacPyMOL.app/pymol/modules/pymol/parsing.py", line 408, in run_file
File "qkabsch.py", line 86, in ?
import numpy
ImportError: No module named numpy
</source>

'''Solution''': This problem occurs under [http://www.apple.com/macosx Apple Mac OS X] if (a) the Apple's python executable on your machine (/usr/bin/python, currently version 2.3.5) is superseded by [http://fink.sourceforge.net/ Fink]'s python executable (/sw/bin/python, currently version 2.5) and (b) you are using [http://delsci.com/rel/099/#MacOSX precompiled versions of PyMOL] (MacPyMOL, PyMOLX11Hybrid or PyMOL for Mac OS X/X11). These executables ignore Fink's python and instead use Apple's - so, in order to run CE Align, one must install NumPy (as well as CE Align itself) using Apple's python. To do so, first download the [http://sourceforge.net/project/showfiles.php?group_id=1369&package_id=175103 Numpy source code archive] (currently version 1.0.1), unpack it, change directory to numpy-1.0.1 and specify the full path to Apple's python executable during installation: <tt>sudo /usr/bin/python setup.py install | tee install.log</tt>. Then, donwload the [http://www.pymolwiki.org/index.php/Cealign#The_Code CE Align source code archive] (currently version 0.2), unpack it, change directory to cealign-0.2 and finally install CE Align as follows: <tt>sudo /usr/bin/python setup.py install | tee install.log</tt>.
[[User:Lucajovine|Luca Jovine]] 05:11, 25 January 2007 (CST).

=== The Function SimpAlign() is not found ===
'''Problem''': Running CE Align gives the following error message:
<source lang="python">
PyMOL>cealign 1CLL,1GGZ
Traceback (most recent call last):
File "C:\Program Files (x86)\DeLano Scientific\PyMOL/modules\pymol\parser.py", line 203, in parse
result=apply(kw[nest][0],args[nest],kw_args[nest])
File "py24/Lib/cealign.py", line 177, in cealign
curScore = simpAlign( matA, matB, mol1, mol2, stored.mol1, stored.mol2, align=0, L=len(matA) )
NameError: global name 'simpAlign' is not defined
</source>
I am running PyMOL v. 0.99rc6 on Win XP Professional x64 edition version 2003 sp2 and have followed the windows install procedure as described above.

'''Answer''': This simply means that PyMOL couldn't find the simplAlign function. To let PyMOL know about this, you must run the following commands before running [[cealign]]:
<source lang="python">
run /your/path/to/cealign/qkabsch.py
run /your/path/to/cealign/cealign.py
</source>
but most people that use cealign would just put these two lines in their '''.pymolrc''' file.

=== Short Alignments Don't Work ===
If you are trying to align fewer than 16 residues then use [[align]], [[super]], or [[optAlign]]. CE uses a window size of 8; and to build a path of more than one window, you need 2*8=16 residues. I will insert some code to re-route small alignments to one of the aforementioned alignment algorithms.

=== It Worked A Second Ago! ===
[[Image:Rewind.png|thumb|right|Showing the rewind button to rewind to state 1.]]

If you were using cealign (or alignto) and now the commands don't work -- that is, they return an RMSD, but don't actually superimpose the objects, then you have a simple problem dealing with states. Most likely the cause of this oddness was (1) when you issued "cealign prot1, prot2" one of them was actually an ensemble of states or (2) you are trying to align to proteins with only one state, but are not looking at state one (because the last protein you were considering had more than one state and you quit editing that protein on a state that's not state 1). To fix this, use the rewind button to get the proteins back into state 1 & reissue the cealign/alignto command.

== References ==
Text taken from PubMed and formatted for the wiki. The first reference is the most important for this code.

# Shindyalov IN, Bourne PE. '''Protein structure alignment by incremental combinatorial extension (CE) of the optimal path.''' ''Protein Eng.'' 1998 Sep;11(9):739-47. PMID: 9796821 [PubMed - indexed for MEDLINE]
# Jia Y, Dewey TG, Shindyalov IN, Bourne PE. '''A new scoring function and associated statistical significance for structure alignment by CE.''' ''J Comput Biol.'' 2004;11(5):787-99. PMID: 15700402 [PubMed - indexed for MEDLINE]
# Pekurovsky D, Shindyalov IN, Bourne PE. '''A case study of high-throughput biological data processing on parallel platforms.''' ''Bioinformatics.'' 2004 Aug 12;20(12):1940-7. Epub 2004 Mar 25. PMID: 15044237 [PubMed - indexed for MEDLINE]
# Shindyalov IN, Bourne PE. '''An alternative view of protein fold space.''' ''Proteins.'' 2000 Feb 15;38(3):247-60. PMID: 10713986 [PubMed - indexed for MEDLINE]

== License ==
The CEAlign and all its subprograms that I wrote, are released under the open source Free BSD License (BSDL).

[[Category:Script_Library]]
[[Category:Structure_Alignment|Cealign]]

Cealign

2009-07-17T17:43:42Z

Jedgold: /* Requirements */

Cealign plugin

2009-07-17T17:42:42Z

Jedgold: /* Requirements */

== Introduction ==

'''Go directly to [[Cealign#Version_0.8-RBS|DOWNLOAD]]'''

This page is the home page of the open-source CEAlign PyMOL plugin. The CE algorithm is a fast and accurate protein structure alignment algorithm, pioneered by Drs. Shindyalov and Bourne (See
References). There are a few changes from the original CE publication (See Notes).

The source code is implemented in C with the rotations finally done by Numpy in Python. Because the computationally complex portion of the code is written in C, it's quick. That is, on my machines --- relatively fast 64-bit machines --- I can align two 400+ amino acid structures in about 0.300 s with the C++ implementation.

This plugs into PyMol very easily. See [[Cealign#The_Code|the code]] and [[Cealign#Examples|examples]] for installation and usage.

== Comparison to PyMol ==
'''Why should you use this?'''

PyMOL's structure alignment algorithm is fast and robust. However, its first step is to perform a sequence alignment of the two selections. Thus, proteins in the '''twilight zone''' or those having a low sequence identity, may not align well. Because CE is a structure-based alignment, this is not a problem. Consider the following example. The image at LEFT was the result of CE-aligning two proteins (1C0M chain B to 1BCO). The result is '''152''' aligned (alpha carbons) residues (not atoms) at '''4.96 Angstroms'''. The image on the RIGHT shows the results from PyMol's align command: an alignment of '''221 atoms''' (not residues) at an RMSD of '''15.7 Angstroms'''.

<gallery>
Image:cealign_ex1.png|Cealign's results (152 aligned; 4.96 Ang.)
Image:pymol_align.png|PyMol's results (763 atoms; 18.4 Ang. )
</gallery>

=== Fit vs. optAlign ===
====Take Home messages====
* [[fit]] and [[optAlign]] perform nearly equally as well
* if you need an algorithm with an appropriate reference, use [[optAlign]] (references at bottom of page).
* [[fit]] is faster -- if you're aligning many structures, use it over [[optAlign]]

====Discussion====
[[optAlign]] is a function within the [[Cealign]] package that performs the optimal superposition of two objects of equal length. [[optAlign]] follows the Kabsch algorithm which is a closed form, and provably optimal solution to the problem. [[fit]] on the other hand uses the Jacobi rotations to iteratively arrive at the solution of optimal superposition. The difference in error between [[optAilgn]] and [[fit]] seems to be a non-issue (see below) as they both arrive at equivalent solutions for the rotation matrix. The two algorithms are undertake different approaches to orthogonally diagonalizing the correlation matrix.

PyMOL's [[fit]] is fast and works well. If you have to use something with a known reference then check out the "optAlign" function from the qkabsch.py file that comes with this [[Calign]] package. If not, you can just use [[fit]] and avoid installing new software. :-)

optAlign is slower than fit. I just tested both on a sample NMR ensemble; and, while not an extensive validation of "fit" it shows that (1) fit is faster; and (2) fit gets the same exact RMSD as "optAlign" (when optAlign is told to use all atoms, not just CA). To make optAlign use all atoms and not just the alpha-carbon backbones, comment out (that is, put a "#" at the start of lines 183 and 184 in qkabsch.py, where it says "CUT HERE").

<source lang="python">
fetch 1nmr
split_states 1nmr
delete 1nmr

# compare fit and optAlign RMSDs
for x in cmd.get_names(): print cmd.fit("1nmr_0001", x)
for x in cmd.get_names(): optAlign(x, "1nmr_0001")
</source>
<source lang="bash">
# results from fit
0.0
4.50344991684
5.33588504791
5.78613853455
7.25597000122
6.67145586014
3.25131297112
3.36766290665
6.74802017212
5.1579709053
5.96959495544
6.68093347549
4.13217163086
5.51539039612
6.24266338348
6.03838825226
5.01363992691
5.33336305618
6.87617444992
7.797062397

#results from optAlign
RMSD=0.000000
RMSD=4.503450
RMSD=5.335886
RMSD=5.786138
RMSD=7.255970
RMSD=6.671456
RMSD=3.251313
RMSD=3.367663
RMSD=6.748021
RMSD=5.157971
RMSD=5.969595
RMSD=6.680934
RMSD=4.132172
RMSD=5.515390
RMSD=6.242664
RMSD=6.038388
RMSD=5.013640
RMSD=5.333363
RMSD=6.876174
RMSD=7.797062
</source>

== Examples ==
=== Usage ===
==== Syntax ====

CEAlign has the semantic, and syntactic formalism of
<source lang="python">
cealign MASTER, TARGET
</source>
where a post-condition of the algorithm is that the coordinates of the '''MASTER''' protein are unchanged. This allows for easier multi-protein alignments. For example,
<source lang="python">
cealign 1AUE, 1BZ4
cealign 1AUE, 1B68
cealign 1AUE, 1A7V
cealign 1AUE, 1CPR
</source>
will superimpose all the TARGETS onto the MASTER.

=====Examples=====
<source lang="python">
cealign 1cll and i. 42-55, 1ggz and c. A
cealign 1kao, 1ctq
cealign 1fao, 1eaz
</source>

=====Multiple Structure Alignments=====
Use the '''alignto''' command, now provided with cealign. Just type,
<source lang="python">
alignto PROT
</source>
to align all your proteins in PyMOL to the one called, '''PROT'''.

=== Results ===
See '''Changes''' for updates. But, overall, the results here are great.

<gallery>
Image:v7_1fao_1eaz.png|EASY: 1FAO vs. 1EAZ; 96 residues, 1.28 Ang
Image:v7_1cbs_1hmt.png|EASY: 1CBS vs. 1HMT; 128 residues, 2.01 Ang
Image:v7_1a15_1b50.png|MODERATE: 1A15 vs 1B50; 56 residues, 2.54 Ang.
Image:v7_1oan_1s6n.png|EASY: 1OAN vs. 1S6N (state 1); 96 residues aligned to 3.83 Ang. RMSD.
Image:v7_1rlw_1byn.png|HARD: 1RLW to 1BYN; 104 residues; 2.21 Ang.
Image:v7_1ten_3hhr.png|HARD: 1TEN vs. 3HHR; 80 residues, 2.91 Ang.
Image:v7_2sim_1nsb.png|HARD: 2SIM vs. 1NSB; 272 residues, 4.93 Ang.
Image:v7_1cew_1mol.png|HARD: 1CEW vs. 1MOL; 80 residues, 4.03 Ang.
</gallery>

== Installation ==

===Mac OS X (10.5)===
[[Image:Cealign mac os x.png|300px|thumb|center|CEAlign running on Mac OS X (10.5)]]
* Install PyMOL under fink.
* Install Numpy for fink:
<source lang="bash">
/sw/bin/fink install scipy-core-py25
</source>
* Download and install cealign (download instructions below)
<source lang="bash">
sudo /sw/bin/python setup.py install
</source>
* In PyMOL, run the two scripts needed for cealing: "cealign.py" and "qkabsch.py". These are located in the cealign directory you previously downloaded.
* Voila!
* Note that the above python version must match the same version that is used by PyMOL. If you are using the pre-compiled version of MacPyMOL, the above instructions won't work.

===Windows systems===
====CEAlign 0.9====
This is a Win32 build of CEAlign 0.9 [http://pymolwiki.org/index.php/Cealign#Beta_Version_0.9]
=====Requirements=====
* Christoph Gohlke's latest '''unofficial''' PyMol build: http://www.lfd.uci.edu/~gohlke/#pythonlibs
* "Python 2.6.2 Windows installer" from python.org: http://www.python.org/download/
* '''CEAlign09Win32.zip''' from: http://users.umassmed.edu/shivender.shandilya/pymol/CEAlign09Win32.zip
=====Directions=====
# Download the '''CEAlign09Win32.zip''' file
# Unzip the downloaded file and follow the directions as per the included README.txt
# Enjoy the ''awesomeness'' that is CEAlign!
====CEAlign 0.8====
This is a quick and dirty method to use CEAlign 0.8 on Win32 system with the '''official''' Pymol builds...
=====Requirements=====
* Latest PyMol, installed on your system
* Numpy for python 2.4 -- quick download of just what's needed: http://users.umassmed.edu/shivender.shandilya/cealign08/numpy.zip
[Note: If this file is corrupt, you may download the latest 'Numpy for Python 2.4' directly from SourceForge.net
* Pre-compiled ccealign.pyd python module: http://users.umassmed.edu/Shivender.Shandilya/pymol/cealign08/ccealign.zip
* Modified pymolrc: http://users.umassmed.edu/Shivender.Shandilya/pymol/cealign08/pymolrc
* cealign.py and qkabsch.py from the Cealign-0.8-RBS package: download below

=====Directions=====
# Unzip the numpy.zip file, which will give you a folder named '''numpy'''
# Move this entire folder to: C:\Program Files\DeLano Scientific\PyMOL\modules\ (or the corresponding location on your system)
# Unzip ccealign.zip, which will give you a file called '''ccealign.pyd'''
# Move this pyd file to: C:\Program Files\DeLano Scientific\PyMOL\py24\DLLs\ (or the corresponding location on your system)
# Copy the downloaded '''pymolrc''' file to: C:\Program Files\DeLano Scientific\PyMOL\ (or the corresponding location on your system)
# Extract and copy the files cealign.py and qkabsch.py from the Cealign-0.8-RBS package to: C:\Program Files\DeLano Scientific\PyMOL\py24\Lib\ (or the corresponding location on your system)
# Run PyMol and load some molecules
# Run this command in Pymol: '''cealign molecule1, molecule2'''
# Enjoy!

===Gentoo Linux===
Add the science overlay via
layman -a sci
and emerge the cealign plugin
emerge pymol-plugins-cealign

===*nix systems===
====Requirements====
* C compiler
* Python 2.4+ with distutils
* Numpy
** for User-compiled PyMOL: <source lang="python">python setup.py install</source>
** for the precompiled version of PyMOL <source lang="python">python setup.py install --prefix "" --root /DIR_TO/pymol/ext/</source>

====Directions====
# uncompress the distribution file '''cealign-VERSION.tgz'''
# cd cealign-VERSION
# sudo python setup.py install # if you installed by PyMOL by hand
## python setup.py install --prefix "" --root /DIR/TO/pymol/ext/ # if you are using the precompiled binary download
# insert "run DIR_TO_CEALIGN/cealign.py" and "run DIR_TO_CEALIGN/qkabsch.py" into your '''.pymolrc''' file, or just run the two Python scripts by hand.
# load some molecules
# run, '''cealign molecule1, molecule2'''
# enjoy

=====Pre-compiled Hackish Install=====
For those people that prefer to use the pre-compiled version of PyMOL, here are the basics for your install. '''This is a poor method of installing Cealign. I suggest users compile and install their own PyMOL.''' The final goal is to get
# '''ccealign.so''' module into '''PYMOL/ext/lib/python2.4/site-packages'''
# numpy installed (get the numpy directory into (or linked into) '''PYMOL/ext/lib/python2.4/site-packages'''
# and be able to run cealign.py and qkabsch.py from PyMOL.
If you can do the above three steps, '''cealign''' should run from the pre-compiled PyMOL.

In more detail, on a completely fictitious machine --- that is, I created the following commands from a fake machine and I don't expect a copy/paste of this to work '''anywhere''', but the commands should be helpful enough to those who need it:
<source lang="python">
# NOTES:
# This is fake code: don't copy/paste it.
#
# PYMOL='dir to precompiled PyMOL install'
# CEALIGN='dir where you will unpack cealign'
# replace lib with lib64 for x86-64
# install numpy
apt-get install numpy

# link numpy to PyMOL
ln -s /usr/local/lib/python2.4/site-packages/numpy PYMOL/ext/lib/python2.4/site-packages

# download and install Cealign
wget http://www.pymolwiki.org/images/e/ed/Cealign-0.6.tar.bz2
tar -jxvf Cealign-0.6.tar.bz2
cd cealign-0.6
sudo python setup.py build
cp build/lib-XYZ-linux/ccealign.so PYMOL/ext/lib/python2.4/site-packages

# run pymol and try it out
pymol
run CEALIGN/cealign.py
run CEALIGN/qkabsch.py
fetch 1cew 1mol, async=0
cealign 1c, 1m
</source>

== The Code ==
Please unpack and read the documentation. All comments/questions should be directed to Jason Vertrees (javertre _at_ utmb ...dot... edu).

'''LATEST IS v0.8-RBS'''. (Dedicated to Bryan Sutton for allowing me to use his computer for testing.)

=== Version 0.8-RBS ===
* '''Download: [[Media:Cealign-0.8-RBS.tar.bz2|CE Align v0.8-RBS]] (bz2)'''
* '''Download: [[Media:Cealign-0.8-RBS.zip|CE Align v0.8-RBS]] (zip)'''

=== Beta Version 0.9 ===
Use at your own peril. Please report any problems or inconsistent alignments to this discussion page, or to me directly; my email address all over this page.

'''Improvements/Changes''':
* All C++
** So, faster
** comes with the dependencies built in
* No numpy

''' Download: [[Media:Cealign-0.9.zip|CE Align v0.9]] (zip)'''

== Coming Soon ==
* Windows binary
* Linux Binaries (32bit, x86-64)
* Better instructions for precompiled distributions
* Optimization

== Updates ==

=== 2008-03-25 ===
Pure C++ code released. See the beta version above.

=== 2007-04-14 ===
v0.8-RBS source updated. Found the bug that had been plaguing 32-bit machines. This should be the last release for a little while.

Also, I provide the option of aligning based solely upon RMSD or upon the better CE-Score. See the '''References''' for information on the '''CE Score'''.

== Troubleshooting ==

Post your problems/solutions here.

=== Unicode Issues in Python/Numpy ===
'''Problem''': Running/Installing cealign gives
<source lang="python">
Traceback (most recent call last):
File "/home/byron/software/pymol_1.00b17/pymol/modules/pymol/parser.py",
line 308, in parse
File "/home/byron/software/pymol_1.00b17/pymol/modules/pymol/parsing.py",
line 410, in run_file
File "qkabsch.py", line 86, in ?
import numpy
File "/usr/lib/python2.4/site-packages/numpy/__init__.py", line 36, in ?
import core
File "/usr/lib/python2.4/site-packages/numpy/core/__init__.py", line 5, in ?
import multiarray
ImportError: /home/byron/software/pymol/ext/lib/python2.4/site-packages/numpy/core/multiarray.so:
undefined symbol: _PyUnicodeUCS4_IsWhitespace
</source>
where the important line is
<source lang="python">
undefined symbol: _PyUnicodeUCS4_IsWhitespace
</source>

This problem indicates that your Numpy Unicode is using a different byte-size for unicode characters than is the Python distribution your PyMOL is running from. For example, this can happen if you use the pre-built PyMOL and some other pre-built Numpy package.

'''Solution''': Hand-install Numpy.

=== LinAlg Module Not Found ===
'''Problem''': Running CE Align gives the following error message:
<source lang="python">
run qkabsch.py
Traceback (most recent call last):
File "/usr/lib/python2.4/site-packages/pymol/parser.py", line 285, in parse
parsing.run_file(exp_path(args[nest][0]),pymol_names,pymol_names)
File "/usr/lib/python2.4/site-packages/pymol/parsing.py", line 407, in run_file
execfile(file,global_ns,local_ns)
File "qkabsch.py", line 86, in ?
import numpy
File "/usr/lib/python2.4/site-packages/numpy/__init__.py", line 40, in ?
import linalg
ImportError: No module named linalg
</source>

'''Solution''': You do not have the linear algebra module installed (or Python can't find it) on your machine. One workaround is to install [http://www.scipy.org/ Scientific Python]. (on debian/ubuntu this can be done by: sudo apt-get install python-scipy) Another is to reinstall the Numpy package from source, ensuring that you have the necessary requirements for the linear algebra module (linpack, lapack, fft, etc.).

=== CCEAlign & NumPy Modules Not Found ===
'''Problem''': Running CE Align gives the following error message:
<source lang="python">
PyMOL>run cealign.py
Traceback (most recent call last):
File "/home/local/warren/MacPyMOL060530/build/Deployment/MacPyMOL.app/pymol/modules/pymol/parser.py", line 297, in parse
File "/home/local/warren/MacPyMOL060530/build/Deployment/MacPyMOL.app/pymol/modules/pymol/parsing.py", line 408, in run_file
File "/usr/local/pymol/scripts/cealign-0.1/cealign.py", line 59, in ?
from ccealign import ccealign
ImportError: No module named ccealign
run qkabsch.py
Traceback (most recent call last):
File "/home/local/warren/MacPyMOL060530/build/Deployment/MacPyMOL.app/pymol/modules/pymol/parser.py", line 297, in parse
File "/home/local/warren/MacPyMOL060530/build/Deployment/MacPyMOL.app/pymol/modules/pymol/parsing.py", line 408, in run_file
File "qkabsch.py", line 86, in ?
import numpy
ImportError: No module named numpy
</source>

'''Solution''': This problem occurs under [http://www.apple.com/macosx Apple Mac OS X] if (a) the Apple's python executable on your machine (/usr/bin/python, currently version 2.3.5) is superseded by [http://fink.sourceforge.net/ Fink]'s python executable (/sw/bin/python, currently version 2.5) and (b) you are using [http://delsci.com/rel/099/#MacOSX precompiled versions of PyMOL] (MacPyMOL, PyMOLX11Hybrid or PyMOL for Mac OS X/X11). These executables ignore Fink's python and instead use Apple's - so, in order to run CE Align, one must install NumPy (as well as CE Align itself) using Apple's python. To do so, first download the [http://sourceforge.net/project/showfiles.php?group_id=1369&package_id=175103 Numpy source code archive] (currently version 1.0.1), unpack it, change directory to numpy-1.0.1 and specify the full path to Apple's python executable during installation: <tt>sudo /usr/bin/python setup.py install | tee install.log</tt>. Then, donwload the [http://www.pymolwiki.org/index.php/Cealign#The_Code CE Align source code archive] (currently version 0.2), unpack it, change directory to cealign-0.2 and finally install CE Align as follows: <tt>sudo /usr/bin/python setup.py install | tee install.log</tt>.
[[User:Lucajovine|Luca Jovine]] 05:11, 25 January 2007 (CST).

=== The Function SimpAlign() is not found ===
'''Problem''': Running CE Align gives the following error message:
<source lang="python">
PyMOL>cealign 1CLL,1GGZ
Traceback (most recent call last):
File "C:\Program Files (x86)\DeLano Scientific\PyMOL/modules\pymol\parser.py", line 203, in parse
result=apply(kw[nest][0],args[nest],kw_args[nest])
File "py24/Lib/cealign.py", line 177, in cealign
curScore = simpAlign( matA, matB, mol1, mol2, stored.mol1, stored.mol2, align=0, L=len(matA) )
NameError: global name 'simpAlign' is not defined
</source>
I am running PyMOL v. 0.99rc6 on Win XP Professional x64 edition version 2003 sp2 and have followed the windows install procedure as described above.

'''Answer''': This simply means that PyMOL couldn't find the simplAlign function. To let PyMOL know about this, you must run the following commands before running [[cealign]]:
<source lang="python">
run /your/path/to/cealign/qkabsch.py
run /your/path/to/cealign/cealign.py
</source>
but most people that use cealign would just put these two lines in their '''.pymolrc''' file.

=== Short Alignments Don't Work ===
If you are trying to align fewer than 16 residues then use [[align]], [[super]], or [[optAlign]]. CE uses a window size of 8; and to build a path of more than one window, you need 2*8=16 residues. I will insert some code to re-route small alignments to one of the aforementioned alignment algorithms.

=== It Worked A Second Ago! ===
[[Image:Rewind.png|thumb|right|Showing the rewind button to rewind to state 1.]]

If you were using cealign (or alignto) and now the commands don't work -- that is, they return an RMSD, but don't actually superimpose the objects, then you have a simple problem dealing with states. Most likely the cause of this oddness was (1) when you issued "cealign prot1, prot2" one of them was actually an ensemble of states or (2) you are trying to align to proteins with only one state, but are not looking at state one (because the last protein you were considering had more than one state and you quit editing that protein on a state that's not state 1). To fix this, use the rewind button to get the proteins back into state 1 & reissue the cealign/alignto command.

== References ==
Text taken from PubMed and formatted for the wiki. The first reference is the most important for this code.

# Shindyalov IN, Bourne PE. '''Protein structure alignment by incremental combinatorial extension (CE) of the optimal path.''' ''Protein Eng.'' 1998 Sep;11(9):739-47. PMID: 9796821 [PubMed - indexed for MEDLINE]
# Jia Y, Dewey TG, Shindyalov IN, Bourne PE. '''A new scoring function and associated statistical significance for structure alignment by CE.''' ''J Comput Biol.'' 2004;11(5):787-99. PMID: 15700402 [PubMed - indexed for MEDLINE]
# Pekurovsky D, Shindyalov IN, Bourne PE. '''A case study of high-throughput biological data processing on parallel platforms.''' ''Bioinformatics.'' 2004 Aug 12;20(12):1940-7. Epub 2004 Mar 25. PMID: 15044237 [PubMed - indexed for MEDLINE]
# Shindyalov IN, Bourne PE. '''An alternative view of protein fold space.''' ''Proteins.'' 2000 Feb 15;38(3):247-60. PMID: 10713986 [PubMed - indexed for MEDLINE]

== License ==
The CEAlign and all its subprograms that I wrote, are released under the open source Free BSD License (BSDL).

[[Category:Script_Library]]
[[Category:Structure_Alignment|Cealign]]

Cealign

2009-07-17T17:42:42Z

Jedgold: /* Requirements */

== Introduction ==

'''Go directly to [[Cealign#Version_0.8-RBS|DOWNLOAD]]'''

This page is the home page of the open-source CEAlign PyMOL plugin. The CE algorithm is a fast and accurate protein structure alignment algorithm, pioneered by Drs. Shindyalov and Bourne (See
References). There are a few changes from the original CE publication (See Notes).

The source code is implemented in C with the rotations finally done by Numpy in Python. Because the computationally complex portion of the code is written in C, it's quick. That is, on my machines --- relatively fast 64-bit machines --- I can align two 400+ amino acid structures in about 0.300 s with the C++ implementation.

This plugs into PyMol very easily. See [[Cealign#The_Code|the code]] and [[Cealign#Examples|examples]] for installation and usage.

== Comparison to PyMol ==
'''Why should you use this?'''

PyMOL's structure alignment algorithm is fast and robust. However, its first step is to perform a sequence alignment of the two selections. Thus, proteins in the '''twilight zone''' or those having a low sequence identity, may not align well. Because CE is a structure-based alignment, this is not a problem. Consider the following example. The image at LEFT was the result of CE-aligning two proteins (1C0M chain B to 1BCO). The result is '''152''' aligned (alpha carbons) residues (not atoms) at '''4.96 Angstroms'''. The image on the RIGHT shows the results from PyMol's align command: an alignment of '''221 atoms''' (not residues) at an RMSD of '''15.7 Angstroms'''.

<gallery>
Image:cealign_ex1.png|Cealign's results (152 aligned; 4.96 Ang.)
Image:pymol_align.png|PyMol's results (763 atoms; 18.4 Ang. )
</gallery>

=== Fit vs. optAlign ===
====Take Home messages====
* [[fit]] and [[optAlign]] perform nearly equally as well
* if you need an algorithm with an appropriate reference, use [[optAlign]] (references at bottom of page).
* [[fit]] is faster -- if you're aligning many structures, use it over [[optAlign]]

====Discussion====
[[optAlign]] is a function within the [[Cealign]] package that performs the optimal superposition of two objects of equal length. [[optAlign]] follows the Kabsch algorithm which is a closed form, and provably optimal solution to the problem. [[fit]] on the other hand uses the Jacobi rotations to iteratively arrive at the solution of optimal superposition. The difference in error between [[optAilgn]] and [[fit]] seems to be a non-issue (see below) as they both arrive at equivalent solutions for the rotation matrix. The two algorithms are undertake different approaches to orthogonally diagonalizing the correlation matrix.

PyMOL's [[fit]] is fast and works well. If you have to use something with a known reference then check out the "optAlign" function from the qkabsch.py file that comes with this [[Calign]] package. If not, you can just use [[fit]] and avoid installing new software. :-)

optAlign is slower than fit. I just tested both on a sample NMR ensemble; and, while not an extensive validation of "fit" it shows that (1) fit is faster; and (2) fit gets the same exact RMSD as "optAlign" (when optAlign is told to use all atoms, not just CA). To make optAlign use all atoms and not just the alpha-carbon backbones, comment out (that is, put a "#" at the start of lines 183 and 184 in qkabsch.py, where it says "CUT HERE").

<source lang="python">
fetch 1nmr
split_states 1nmr
delete 1nmr

# compare fit and optAlign RMSDs
for x in cmd.get_names(): print cmd.fit("1nmr_0001", x)
for x in cmd.get_names(): optAlign(x, "1nmr_0001")
</source>
<source lang="bash">
# results from fit
0.0
4.50344991684
5.33588504791
5.78613853455
7.25597000122
6.67145586014
3.25131297112
3.36766290665
6.74802017212
5.1579709053
5.96959495544
6.68093347549
4.13217163086
5.51539039612
6.24266338348
6.03838825226
5.01363992691
5.33336305618
6.87617444992
7.797062397

#results from optAlign
RMSD=0.000000
RMSD=4.503450
RMSD=5.335886
RMSD=5.786138
RMSD=7.255970
RMSD=6.671456
RMSD=3.251313
RMSD=3.367663
RMSD=6.748021
RMSD=5.157971
RMSD=5.969595
RMSD=6.680934
RMSD=4.132172
RMSD=5.515390
RMSD=6.242664
RMSD=6.038388
RMSD=5.013640
RMSD=5.333363
RMSD=6.876174
RMSD=7.797062
</source>

== Examples ==
=== Usage ===
==== Syntax ====

CEAlign has the semantic, and syntactic formalism of
<source lang="python">
cealign MASTER, TARGET
</source>
where a post-condition of the algorithm is that the coordinates of the '''MASTER''' protein are unchanged. This allows for easier multi-protein alignments. For example,
<source lang="python">
cealign 1AUE, 1BZ4
cealign 1AUE, 1B68
cealign 1AUE, 1A7V
cealign 1AUE, 1CPR
</source>
will superimpose all the TARGETS onto the MASTER.

=====Examples=====
<source lang="python">
cealign 1cll and i. 42-55, 1ggz and c. A
cealign 1kao, 1ctq
cealign 1fao, 1eaz
</source>

=====Multiple Structure Alignments=====
Use the '''alignto''' command, now provided with cealign. Just type,
<source lang="python">
alignto PROT
</source>
to align all your proteins in PyMOL to the one called, '''PROT'''.

=== Results ===
See '''Changes''' for updates. But, overall, the results here are great.

<gallery>
Image:v7_1fao_1eaz.png|EASY: 1FAO vs. 1EAZ; 96 residues, 1.28 Ang
Image:v7_1cbs_1hmt.png|EASY: 1CBS vs. 1HMT; 128 residues, 2.01 Ang
Image:v7_1a15_1b50.png|MODERATE: 1A15 vs 1B50; 56 residues, 2.54 Ang.
Image:v7_1oan_1s6n.png|EASY: 1OAN vs. 1S6N (state 1); 96 residues aligned to 3.83 Ang. RMSD.
Image:v7_1rlw_1byn.png|HARD: 1RLW to 1BYN; 104 residues; 2.21 Ang.
Image:v7_1ten_3hhr.png|HARD: 1TEN vs. 3HHR; 80 residues, 2.91 Ang.
Image:v7_2sim_1nsb.png|HARD: 2SIM vs. 1NSB; 272 residues, 4.93 Ang.
Image:v7_1cew_1mol.png|HARD: 1CEW vs. 1MOL; 80 residues, 4.03 Ang.
</gallery>

== Installation ==

===Mac OS X (10.5)===
[[Image:Cealign mac os x.png|300px|thumb|center|CEAlign running on Mac OS X (10.5)]]
* Install PyMOL under fink.
* Install Numpy for fink:
<source lang="bash">
/sw/bin/fink install scipy-core-py25
</source>
* Download and install cealign (download instructions below)
<source lang="bash">
sudo /sw/bin/python setup.py install
</source>
* In PyMOL, run the two scripts needed for cealing: "cealign.py" and "qkabsch.py". These are located in the cealign directory you previously downloaded.
* Voila!
* Note that the above python version must match the same version that is used by PyMOL. If you are using the pre-compiled version of MacPyMOL, the above instructions won't work.

===Windows systems===
====CEAlign 0.9====
This is a Win32 build of CEAlign 0.9 [http://pymolwiki.org/index.php/Cealign#Beta_Version_0.9]
=====Requirements=====
* Christoph Gohlke's latest '''unofficial''' PyMol build: http://www.lfd.uci.edu/~gohlke/#pythonlibs
* "Python 2.6.2 Windows installer" from python.org: http://www.python.org/download/
* '''CEAlign09Win32.zip''' from: http://users.umassmed.edu/shivender.shandilya/pymol/CEAlign09Win32.zip
=====Directions=====
# Download the '''CEAlign09Win32.zip''' file
# Unzip the downloaded file and follow the directions as per the included README.txt
# Enjoy the ''awesomeness'' that is CEAlign!
====CEAlign 0.8====
This is a quick and dirty method to use CEAlign 0.8 on Win32 system with the '''official''' Pymol builds...
=====Requirements=====
* Latest PyMol, installed on your system
* Numpy for python 2.4 -- quick download of just what's needed: http://users.umassmed.edu/shivender.shandilya/cealign08/numpy.zip
[Note: If this file is corrupt, you may download the latest 'Numpy for Python 2.4' directly from SourceForge.net
* Pre-compiled ccealign.pyd python module: http://users.umassmed.edu/Shivender.Shandilya/pymol/cealign08/ccealign.zip
* Modified pymolrc: http://users.umassmed.edu/Shivender.Shandilya/pymol/cealign08/pymolrc
* cealign.py and qkabsch.py from the Cealign-0.8-RBS package: download below

=====Directions=====
# Unzip the numpy.zip file, which will give you a folder named '''numpy'''
# Move this entire folder to: C:\Program Files\DeLano Scientific\PyMOL\modules\ (or the corresponding location on your system)
# Unzip ccealign.zip, which will give you a file called '''ccealign.pyd'''
# Move this pyd file to: C:\Program Files\DeLano Scientific\PyMOL\py24\DLLs\ (or the corresponding location on your system)
# Copy the downloaded '''pymolrc''' file to: C:\Program Files\DeLano Scientific\PyMOL\ (or the corresponding location on your system)
# Extract and copy the files cealign.py and qkabsch.py from the Cealign-0.8-RBS package to: C:\Program Files\DeLano Scientific\PyMOL\py24\Lib\ (or the corresponding location on your system)
# Run PyMol and load some molecules
# Run this command in Pymol: '''cealign molecule1, molecule2'''
# Enjoy!

===Gentoo Linux===
Add the science overlay via
layman -a sci
and emerge the cealign plugin
emerge pymol-plugins-cealign

===*nix systems===
====Requirements====
* C compiler
* Python 2.4+ with distutils
* Numpy
** for User-compiled PyMOL: <source lang="python">python setup.py install</source>
** for the precompiled version of PyMOL <source lang="python">python setup.py install --prefix "" --root /DIR_TO/pymol/ext/</source>

====Directions====
# uncompress the distribution file '''cealign-VERSION.tgz'''
# cd cealign-VERSION
# sudo python setup.py install # if you installed by PyMOL by hand
## python setup.py install --prefix "" --root /DIR/TO/pymol/ext/ # if you are using the precompiled binary download
# insert "run DIR_TO_CEALIGN/cealign.py" and "run DIR_TO_CEALIGN/qkabsch.py" into your '''.pymolrc''' file, or just run the two Python scripts by hand.
# load some molecules
# run, '''cealign molecule1, molecule2'''
# enjoy

=====Pre-compiled Hackish Install=====
For those people that prefer to use the pre-compiled version of PyMOL, here are the basics for your install. '''This is a poor method of installing Cealign. I suggest users compile and install their own PyMOL.''' The final goal is to get
# '''ccealign.so''' module into '''PYMOL/ext/lib/python2.4/site-packages'''
# numpy installed (get the numpy directory into (or linked into) '''PYMOL/ext/lib/python2.4/site-packages'''
# and be able to run cealign.py and qkabsch.py from PyMOL.
If you can do the above three steps, '''cealign''' should run from the pre-compiled PyMOL.

In more detail, on a completely fictitious machine --- that is, I created the following commands from a fake machine and I don't expect a copy/paste of this to work '''anywhere''', but the commands should be helpful enough to those who need it:
<source lang="python">
# NOTES:
# This is fake code: don't copy/paste it.
#
# PYMOL='dir to precompiled PyMOL install'
# CEALIGN='dir where you will unpack cealign'
# replace lib with lib64 for x86-64
# install numpy
apt-get install numpy

# link numpy to PyMOL
ln -s /usr/local/lib/python2.4/site-packages/numpy PYMOL/ext/lib/python2.4/site-packages

# download and install Cealign
wget http://www.pymolwiki.org/images/e/ed/Cealign-0.6.tar.bz2
tar -jxvf Cealign-0.6.tar.bz2
cd cealign-0.6
sudo python setup.py build
cp build/lib-XYZ-linux/ccealign.so PYMOL/ext/lib/python2.4/site-packages

# run pymol and try it out
pymol
run CEALIGN/cealign.py
run CEALIGN/qkabsch.py
fetch 1cew 1mol, async=0
cealign 1c, 1m
</source>

== The Code ==
Please unpack and read the documentation. All comments/questions should be directed to Jason Vertrees (javertre _at_ utmb ...dot... edu).

'''LATEST IS v0.8-RBS'''. (Dedicated to Bryan Sutton for allowing me to use his computer for testing.)

=== Version 0.8-RBS ===
* '''Download: [[Media:Cealign-0.8-RBS.tar.bz2|CE Align v0.8-RBS]] (bz2)'''
* '''Download: [[Media:Cealign-0.8-RBS.zip|CE Align v0.8-RBS]] (zip)'''

=== Beta Version 0.9 ===
Use at your own peril. Please report any problems or inconsistent alignments to this discussion page, or to me directly; my email address all over this page.

'''Improvements/Changes''':
* All C++
** So, faster
** comes with the dependencies built in
* No numpy

''' Download: [[Media:Cealign-0.9.zip|CE Align v0.9]] (zip)'''

== Coming Soon ==
* Windows binary
* Linux Binaries (32bit, x86-64)
* Better instructions for precompiled distributions
* Optimization

== Updates ==

=== 2008-03-25 ===
Pure C++ code released. See the beta version above.

=== 2007-04-14 ===
v0.8-RBS source updated. Found the bug that had been plaguing 32-bit machines. This should be the last release for a little while.

Also, I provide the option of aligning based solely upon RMSD or upon the better CE-Score. See the '''References''' for information on the '''CE Score'''.

== Troubleshooting ==

Post your problems/solutions here.

=== Unicode Issues in Python/Numpy ===
'''Problem''': Running/Installing cealign gives
<source lang="python">
Traceback (most recent call last):
File "/home/byron/software/pymol_1.00b17/pymol/modules/pymol/parser.py",
line 308, in parse
File "/home/byron/software/pymol_1.00b17/pymol/modules/pymol/parsing.py",
line 410, in run_file
File "qkabsch.py", line 86, in ?
import numpy
File "/usr/lib/python2.4/site-packages/numpy/__init__.py", line 36, in ?
import core
File "/usr/lib/python2.4/site-packages/numpy/core/__init__.py", line 5, in ?
import multiarray
ImportError: /home/byron/software/pymol/ext/lib/python2.4/site-packages/numpy/core/multiarray.so:
undefined symbol: _PyUnicodeUCS4_IsWhitespace
</source>
where the important line is
<source lang="python">
undefined symbol: _PyUnicodeUCS4_IsWhitespace
</source>

This problem indicates that your Numpy Unicode is using a different byte-size for unicode characters than is the Python distribution your PyMOL is running from. For example, this can happen if you use the pre-built PyMOL and some other pre-built Numpy package.

'''Solution''': Hand-install Numpy.

=== LinAlg Module Not Found ===
'''Problem''': Running CE Align gives the following error message:
<source lang="python">
run qkabsch.py
Traceback (most recent call last):
File "/usr/lib/python2.4/site-packages/pymol/parser.py", line 285, in parse
parsing.run_file(exp_path(args[nest][0]),pymol_names,pymol_names)
File "/usr/lib/python2.4/site-packages/pymol/parsing.py", line 407, in run_file
execfile(file,global_ns,local_ns)
File "qkabsch.py", line 86, in ?
import numpy
File "/usr/lib/python2.4/site-packages/numpy/__init__.py", line 40, in ?
import linalg
ImportError: No module named linalg
</source>

'''Solution''': You do not have the linear algebra module installed (or Python can't find it) on your machine. One workaround is to install [http://www.scipy.org/ Scientific Python]. (on debian/ubuntu this can be done by: sudo apt-get install python-scipy) Another is to reinstall the Numpy package from source, ensuring that you have the necessary requirements for the linear algebra module (linpack, lapack, fft, etc.).

=== CCEAlign & NumPy Modules Not Found ===
'''Problem''': Running CE Align gives the following error message:
<source lang="python">
PyMOL>run cealign.py
Traceback (most recent call last):
File "/home/local/warren/MacPyMOL060530/build/Deployment/MacPyMOL.app/pymol/modules/pymol/parser.py", line 297, in parse
File "/home/local/warren/MacPyMOL060530/build/Deployment/MacPyMOL.app/pymol/modules/pymol/parsing.py", line 408, in run_file
File "/usr/local/pymol/scripts/cealign-0.1/cealign.py", line 59, in ?
from ccealign import ccealign
ImportError: No module named ccealign
run qkabsch.py
Traceback (most recent call last):
File "/home/local/warren/MacPyMOL060530/build/Deployment/MacPyMOL.app/pymol/modules/pymol/parser.py", line 297, in parse
File "/home/local/warren/MacPyMOL060530/build/Deployment/MacPyMOL.app/pymol/modules/pymol/parsing.py", line 408, in run_file
File "qkabsch.py", line 86, in ?
import numpy
ImportError: No module named numpy
</source>

'''Solution''': This problem occurs under [http://www.apple.com/macosx Apple Mac OS X] if (a) the Apple's python executable on your machine (/usr/bin/python, currently version 2.3.5) is superseded by [http://fink.sourceforge.net/ Fink]'s python executable (/sw/bin/python, currently version 2.5) and (b) you are using [http://delsci.com/rel/099/#MacOSX precompiled versions of PyMOL] (MacPyMOL, PyMOLX11Hybrid or PyMOL for Mac OS X/X11). These executables ignore Fink's python and instead use Apple's - so, in order to run CE Align, one must install NumPy (as well as CE Align itself) using Apple's python. To do so, first download the [http://sourceforge.net/project/showfiles.php?group_id=1369&package_id=175103 Numpy source code archive] (currently version 1.0.1), unpack it, change directory to numpy-1.0.1 and specify the full path to Apple's python executable during installation: <tt>sudo /usr/bin/python setup.py install | tee install.log</tt>. Then, donwload the [http://www.pymolwiki.org/index.php/Cealign#The_Code CE Align source code archive] (currently version 0.2), unpack it, change directory to cealign-0.2 and finally install CE Align as follows: <tt>sudo /usr/bin/python setup.py install | tee install.log</tt>.
[[User:Lucajovine|Luca Jovine]] 05:11, 25 January 2007 (CST).

=== The Function SimpAlign() is not found ===
'''Problem''': Running CE Align gives the following error message:
<source lang="python">
PyMOL>cealign 1CLL,1GGZ
Traceback (most recent call last):
File "C:\Program Files (x86)\DeLano Scientific\PyMOL/modules\pymol\parser.py", line 203, in parse
result=apply(kw[nest][0],args[nest],kw_args[nest])
File "py24/Lib/cealign.py", line 177, in cealign
curScore = simpAlign( matA, matB, mol1, mol2, stored.mol1, stored.mol2, align=0, L=len(matA) )
NameError: global name 'simpAlign' is not defined
</source>
I am running PyMOL v. 0.99rc6 on Win XP Professional x64 edition version 2003 sp2 and have followed the windows install procedure as described above.

'''Answer''': This simply means that PyMOL couldn't find the simplAlign function. To let PyMOL know about this, you must run the following commands before running [[cealign]]:
<source lang="python">
run /your/path/to/cealign/qkabsch.py
run /your/path/to/cealign/cealign.py
</source>
but most people that use cealign would just put these two lines in their '''.pymolrc''' file.

=== Short Alignments Don't Work ===
If you are trying to align fewer than 16 residues then use [[align]], [[super]], or [[optAlign]]. CE uses a window size of 8; and to build a path of more than one window, you need 2*8=16 residues. I will insert some code to re-route small alignments to one of the aforementioned alignment algorithms.

=== It Worked A Second Ago! ===
[[Image:Rewind.png|thumb|right|Showing the rewind button to rewind to state 1.]]

If you were using cealign (or alignto) and now the commands don't work -- that is, they return an RMSD, but don't actually superimpose the objects, then you have a simple problem dealing with states. Most likely the cause of this oddness was (1) when you issued "cealign prot1, prot2" one of them was actually an ensemble of states or (2) you are trying to align to proteins with only one state, but are not looking at state one (because the last protein you were considering had more than one state and you quit editing that protein on a state that's not state 1). To fix this, use the rewind button to get the proteins back into state 1 & reissue the cealign/alignto command.

== References ==
Text taken from PubMed and formatted for the wiki. The first reference is the most important for this code.

# Shindyalov IN, Bourne PE. '''Protein structure alignment by incremental combinatorial extension (CE) of the optimal path.''' ''Protein Eng.'' 1998 Sep;11(9):739-47. PMID: 9796821 [PubMed - indexed for MEDLINE]
# Jia Y, Dewey TG, Shindyalov IN, Bourne PE. '''A new scoring function and associated statistical significance for structure alignment by CE.''' ''J Comput Biol.'' 2004;11(5):787-99. PMID: 15700402 [PubMed - indexed for MEDLINE]
# Pekurovsky D, Shindyalov IN, Bourne PE. '''A case study of high-throughput biological data processing on parallel platforms.''' ''Bioinformatics.'' 2004 Aug 12;20(12):1940-7. Epub 2004 Mar 25. PMID: 15044237 [PubMed - indexed for MEDLINE]
# Shindyalov IN, Bourne PE. '''An alternative view of protein fold space.''' ''Proteins.'' 2000 Feb 15;38(3):247-60. PMID: 10713986 [PubMed - indexed for MEDLINE]

== License ==
The CEAlign and all its subprograms that I wrote, are released under the open source Free BSD License (BSDL).

[[Category:Script_Library]]
[[Category:Structure_Alignment|Cealign]]

Talk:Cealign

2009-07-17T17:41:11Z

Jedgold:

The numpy zip file provided in the Windows section unzips with fatal errors.

Sean

: And the instructions to download NumpPy from sourceforge and install the folder into the /PyMol/modules/ folder result in an error when numpy is called (numpy shouldn't be called outside the source folder - apparently it needs to be called from <i>inside</i> the folder?) [I used Numpy-1.2.1.tar.gz - maybe I need to use the superpack installer?] [[User:Jedgold|Jedgold]] 17:41, 17 July 2009 (UTC)