Tutorial(First Steps) - Revision history

Kay: /* A beginner's walk-through to XDS */ update

2023-07-15T14:46:44Z

A beginner's walk-through to XDS: update

← Older revision		Revision as of 16:46, 15 July 2023
Line 3:		Line 3:
	This tutorial is directed at people who are beginners to XDS and do not want to start reading about all the technical details but rather want their images processed. Other processing programs are often more attractive to new users because using a GUI make starting easier than a [[XDS.INP\|script file]]. If you notice a mistake or gap in this tutorial, please contact the authors.		This tutorial is directed at people who are beginners to XDS and do not want to start reading about all the technical details but rather want their images processed. Other processing programs are often more attractive to new users because using a GUI make starting easier than a [[XDS.INP\|script file]]. If you notice a mistake or gap in this tutorial, please contact the authors.

	In the following, the manual mode of setting up XDS.INP is explained. ~~But there~~ is also a [[generate_XDS.INP\|script]] that ~~does most of this~~ automatically, at least for common types of detectors.		In the following, the manual mode of setting up [[XDS.INP]] and running XDS is explained.

			There is also a [[generate_XDS.INP\|script]] that sets up XDS.INP automatically, at least for common types of detectors. Much easier than setting up and running XDS manually should be the usage of [[XDSGUI]].

	== Setting up ==		== Setting up ==
Line 9:		Line 11:

	It is not recommended to process the images from within the same directory as the images are. At least create a subdirectory. In many cases the data images are on an external disk or remotely mounted directory with an awfully long path name.		It is not recommended to process the images from within the same directory as the images are. At least create a subdirectory. In many cases the data images are on an external disk or remotely mounted directory with an awfully long path name.
	If ~~you~~ images are "/~~some/where/with/a~~/~~very/long~~/path", [[XDS~~.INP]] may~~ not ~~find~~ the images and one must create a link to the actual directory.		If your images are at a path with embedded blanks, e.g. "/my/USB disk/path", XDS is not able to access the images and one must create a link to the actual directory:
	~~<pre>~~ #> ln -s /~~some~~/~~where/with/a/very/long~~/path images ~~</pre>.~~		#> ln -s "/my/USB disk/path" images

	=== Getting [[XDS.INP]] ===		=== Getting [[XDS.INP]] ===

Kay: add "See also" with link to M.J. Whitley's tutorial

2020-05-02T09:00:33Z

add "See also" with link to M.J. Whitley's tutorial

← Older revision		Revision as of 11:00, 2 May 2020
Line 34:		Line 34:
	Then data processing can start. type <pre>#> xds_par </pre> to run xds and wait until it's finished.		Then data processing can start. type <pre>#> xds_par </pre> to run xds and wait until it's finished.


	~~== See also ==~~

	[https://{{SERVERNAME}}/pub/MWhitley_CSHL-2018_XDS-Tutorial.pdf Matthew J. Whitley's excellent tutorial] about XDS processing with [[XDSGUI]], from the 2018 Cold Spring Harbor X-Ray Methods in Structural Biology Course.

	== Indexing Fails ==		== Indexing Fails ==
Line 59:		Line 55:
	If it deviates by more than 1-2mm from the input distance, check all your parameters again. Is the wavelength really correct, as well as the distance? If you are sure about them, try indexing with only a few images		If it deviates by more than 1-2mm from the input distance, check all your parameters again. Is the wavelength really correct, as well as the distance? If you are sure about them, try indexing with only a few images
	SPOT_RANGE = 1 20		SPOT_RANGE = 1 20


			== See also ==

			[https://{{SERVERNAME}}/pub/MWhitley_CSHL-2018_XDS-Tutorial.pdf Matthew J. Whitley's excellent tutorial] about XDS processing with [[XDSGUI]], from the 2018 Cold Spring Harbor X-Ray Methods in Structural Biology Course.

Kay: /* Editing XDS.INP */

2020-05-02T08:54:52Z

Editing XDS.INP

← Older revision		Revision as of 10:54, 2 May 2020
Line 20:		Line 20:
	Open [[XDS.INP]] with your favourite text editor (e.g. gedit, kate, kwrite, vim, emacs...) and make the following adjustments (from top to bottom):		Open [[XDS.INP]] with your favourite text editor (e.g. gedit, kate, kwrite, vim, emacs...) and make the following adjustments (from top to bottom):

	* '''Pixel Size''' Find out the number of pixels of your detector. A very good program to find this is [http://www.scripps.edu/~arvai/adxv.html adxv] (also see the wiki article [[adxv]]): It allows to view the image header where these numbers often can be found. [[Image:Adxv_menu.jpeg\|~~100px~~\|adxv image viewer, main menu]] [[Image:Adxv_pixelsize.jpeg\|~~100px~~\|adxv showing image header info. Pixel size is highlighted]]		* '''Pixel Size''' Find out the number of pixels of your detector. A very good program to find this is [http://www.scripps.edu/~arvai/adxv.html adxv] (also see the wiki article [[adxv]]): It allows to view the '''image header''' where these numbers often can be found. [[Image:Adxv_menu.jpeg\|200px\|adxv image viewer, main menu]] [[Image:Adxv_pixelsize.jpeg\|300px\|adxv showing image header info. Pixel size is highlighted]]
	* '''Adjusting JOB Card''' Make a copy of the '''JOB''' line in [[XDS.INP]] for reference. Comment out one line by putting a exclamation mark "!" at the beginning of the line and prepare the other one to run the steps from XYCORR to CORRECT.[[Image:XDS_INP_adjustingJOB.jpeg\|~~200px~~\|Adjusting the JOB card in XDS.INP]]		* '''Adjusting JOB Card''' Make a copy of the '''JOB''' line in [[XDS.INP]] for reference. Comment out one line by putting a exclamation mark "!" at the beginning of the line and prepare the other one to run the steps from XYCORR to CORRECT.[[Image:XDS_INP_adjustingJOB.jpeg\|400px\|Adjusting the JOB card in XDS.INP]]
	* '''ORGX and ORGY''' Unless you can guess the direct beam position on the images, ''e.g.'' from ice rings, set both these values to half the detector size. In the case of this example, where the MAR-CCD is 3072x3072 pixels, this means		* '''ORGX and ORGY''' Unless you can guess the direct beam position on the images, ''e.g.'' from ice rings, set both these values to half the detector size. In the case of this example, where the MAR-CCD is 3072x3072 pixels, this means
	ORGX=1536.00 ORGY=1536.00 !Detector origin (pixels).		ORGX=1536.00 ORGY=1536.00 !Detector origin (pixels).
Line 33:		Line 33:

	Then data processing can start. type <pre>#> xds_par </pre> to run xds and wait until it's finished.		Then data processing can start. type <pre>#> xds_par </pre> to run xds and wait until it's finished.


			== See also ==

			[https://{{SERVERNAME}}/pub/MWhitley_CSHL-2018_XDS-Tutorial.pdf Matthew J. Whitley's excellent tutorial] about XDS processing with [[XDSGUI]], from the 2018 Cold Spring Harbor X-Ray Methods in Structural Biology Course.

	== Indexing Fails ==		== Indexing Fails ==

Kay: fix links

2019-10-22T13:31:45Z

fix links

← Older revision		Revision as of 15:31, 22 October 2019
Line 13:		Line 13:

	=== Getting [[XDS.INP]] ===		=== Getting [[XDS.INP]] ===
	You must know the type of detector your data were collected on. Then visit the [http://~~www~~.mpimf-heidelberg.mpg.de~~/~kabsch/xds~~/html_doc/xds_prepare.html XDS Homepage], download the appropriate template and rename it to [[XDS.INP]].		You must know the type of detector your data were collected on. Then visit the [http://xds.mpimf-heidelberg.mpg.de/html_doc/xds_prepare.html XDS Homepage], download the appropriate template and rename it to [[XDS.INP]].

	== Editing [[XDS.INP]] ==		== Editing [[XDS.INP]] ==
	This tutorial uses the template for XDS-MARCCD.INP (templates can be downloaded from [http://~~www~~.mpimf-heidelberg.mpg.de~~/~kabsch/xds~~/html_doc/xds_prepare.html].		This tutorial uses the template for XDS-MARCCD.INP (templates can be downloaded from [http://xds.mpimf-heidelberg.mpg.de/html_doc/xds_prepare.html].

	Open [[XDS.INP]] with your favourite text editor (e.g. gedit, kate, kwrite, vim, emacs...) and make the following adjustments (from top to bottom):		Open [[XDS.INP]] with your favourite text editor (e.g. gedit, kate, kwrite, vim, emacs...) and make the following adjustments (from top to bottom):

Kay: /* Indexing Fails */

2011-03-15T10:42:23Z

Indexing Fails

← Older revision		Revision as of 12:42, 15 March 2011
Line 48:		Line 48:
	DETECTOR ORIGIN (PIXELS) AT 1514.16 1537.27		DETECTOR ORIGIN (PIXELS) AT 1514.16 1537.27
	as improved ORGX and ORGY to [[XDS.INP]] and try indexing again.		as improved ORGX and ORGY to [[XDS.INP]] and try indexing again.
	XDS is quite robust and in many cases this approach works		XDS is quite robust and in many cases this approach works. If not, read [[Obtaining ORGX ORGY]].
	* Check the refined detector distance		* Check the refined detector distance
	DETECTOR ORIGIN (PIXELS) AT 1514.16 1537.27		DETECTOR ORIGIN (PIXELS) AT 1514.16 1537.27

Kay: /* Editing XDS.INP */

2011-03-15T10:25:37Z

Editing XDS.INP

Kay: /* Indexing Fails */

2011-03-15T10:23:08Z

Indexing Fails

Kay: /* Editing XDS.INP */

2011-03-15T10:20:44Z

Editing XDS.INP

← Older revision		Revision as of 12:20, 15 March 2011
Line 24:		Line 24:
	# '''ORGX and ORGY''' Unless you can guess the direct beam position on the images, ''e.g.'' from ice rings, set both these values to half the detector size. In the case of this example, where the MAR-CCD is 3072x3072 pixels, this means		# '''ORGX and ORGY''' Unless you can guess the direct beam position on the images, ''e.g.'' from ice rings, set both these values to half the detector size. In the case of this example, where the MAR-CCD is 3072x3072 pixels, this means
	ORGX=1536.00 ORGY=1536.00 !Detector origin (pixels).		ORGX=1536.00 ORGY=1536.00 !Detector origin (pixels).
	#'''Experiment specific settings''' The following numbers are also usually found in the image header:		# '''Experiment specific settings''' The following numbers are also usually found in the image header (or in your lab notebook, or in logs written by the beamline software):
	DETECTOR_DISTANCE= 150.0 !(mm)		DETECTOR_DISTANCE= 150.0 !(mm)
	OSCILLATION_RANGE=1.0 !degrees (>0)		OSCILLATION_RANGE=1.0 !degrees (>0)
Line 30:		Line 30:
	NAME_TEMPLATE_OF_DATA_FRAMES=./images/tutorial_????.img ! TIFF		NAME_TEMPLATE_OF_DATA_FRAMES=./images/tutorial_????.img ! TIFF
	DATA_RANGE=1 180 !Numbers of first and last data image collected		DATA_RANGE=1 180 !Numbers of first and last data image collected
	#'''Background range''' The default template suggests to use the first 5 images for detecting the average background per image. It does not harm to increase this number to 20 images. Especially with frame width of less than 1 degree you should do this.
	~~BACKGROUND_RANGE=1 20 !Numbers of first and last data image for background~~

	~~This is it to~~ start. type <pre>#> xds_par </pre> to run xds and wait until it's finished.		Then data processing can start. type <pre>#> xds_par </pre> to run xds and wait until it's finished.

	== Indexing Fails ==		== Indexing Fails ==

Kay: /* Editing XDS.INP */

2011-03-15T10:17:43Z

Editing XDS.INP

← Older revision		Revision as of 12:17, 15 March 2011
Line 20:		Line 20:
	Open [[XDS.INP]] with your favourite text editor (e.g. gedit, kate, kwrite, vim, emacs...) and make the following adjustments (from top to bottom):		Open [[XDS.INP]] with your favourite text editor (e.g. gedit, kate, kwrite, vim, emacs...) and make the following adjustments (from top to bottom):

	# '''Pixel Size''' Find out the number of pixels of your detector. A very good program to find ~~aus~~ is [http://www.scripps.edu/~arvai/adxv.html adxv]: It allows to view the image header where these numbers often can be found. [[Image:Adxv_menu.jpeg\|100px\|adxv image viewer, main menu]] [[Image:Adxv_pixelsize.jpeg\|100px\|adxv showing image header info. Pixel size is highlighted]]		# '''Pixel Size''' Find out the number of pixels of your detector. A very good program to find this is [http://www.scripps.edu/~arvai/adxv.html adxv] (also see the wiki article [[adxv]]): It allows to view the image header where these numbers often can be found. [[Image:Adxv_menu.jpeg\|100px\|adxv image viewer, main menu]] [[Image:Adxv_pixelsize.jpeg\|100px\|adxv showing image header info. Pixel size is highlighted]]
	# '''Adjusting JOB Card''' Make a copy of the '''JOB''' line in [[XDS.INP]] for reference. Comment out one line by putting a exclamation mark "!" at the beginning of the line and prepare the other one to run the steps from XYCORR to CORRECT.[[Image:XDS_INP_adjustingJOB.jpeg\|200px\|Adjusting the JOB card in XDS.INP]]		# '''Adjusting JOB Card''' Make a copy of the '''JOB''' line in [[XDS.INP]] for reference. Comment out one line by putting a exclamation mark "!" at the beginning of the line and prepare the other one to run the steps from XYCORR to CORRECT.[[Image:XDS_INP_adjustingJOB.jpeg\|200px\|Adjusting the JOB card in XDS.INP]]
	# '''ORGX and ORGY''' Unless you can guess the direct beam position on the images, ''e.g.'' from ice rings, set both these values to half the detector size. In the case of this example, where the MAR-CCD is 3072x3072 pixels, this means		# '''ORGX and ORGY''' Unless you can guess the direct beam position on the images, ''e.g.'' from ice rings, set both these values to half the detector size. In the case of this example, where the MAR-CCD is 3072x3072 pixels, this means

Kay: /* Getting XDS.INP */

2011-03-15T10:16:29Z

Getting XDS.INP

← Older revision		Revision as of 12:16, 15 March 2011
Line 13:		Line 13:

	=== Getting [[XDS.INP]] ===		=== Getting [[XDS.INP]] ===
	You must know the type of detector your data were collected on. Then visit the [http://www.mpimf-heidelberg.mpg.de/~kabsch/xds/html_doc/xds_prepare.html\|XDS Homepage], download the appropriate template and rename it to [[XDS.INP]].		You must know the type of detector your data were collected on. Then visit the [http://www.mpimf-heidelberg.mpg.de/~kabsch/xds/html_doc/xds_prepare.html XDS Homepage], download the appropriate template and rename it to [[XDS.INP]].

	== Editing [[XDS.INP]] ==		== Editing [[XDS.INP]] ==

← Older revision		Revision as of 12:25, 15 March 2011
Line 20:		Line 20:
	Open [[XDS.INP]] with your favourite text editor (e.g. gedit, kate, kwrite, vim, emacs...) and make the following adjustments (from top to bottom):		Open [[XDS.INP]] with your favourite text editor (e.g. gedit, kate, kwrite, vim, emacs...) and make the following adjustments (from top to bottom):

	# '''Pixel Size''' Find out the number of pixels of your detector. A very good program to find this is [http://www.scripps.edu/~arvai/adxv.html adxv] (also see the wiki article [[adxv]]): It allows to view the image header where these numbers often can be found. [[Image:Adxv_menu.jpeg\|100px\|adxv image viewer, main menu]] [[Image:Adxv_pixelsize.jpeg\|100px\|adxv showing image header info. Pixel size is highlighted]]		* '''Pixel Size''' Find out the number of pixels of your detector. A very good program to find this is [http://www.scripps.edu/~arvai/adxv.html adxv] (also see the wiki article [[adxv]]): It allows to view the image header where these numbers often can be found. [[Image:Adxv_menu.jpeg\|100px\|adxv image viewer, main menu]] [[Image:Adxv_pixelsize.jpeg\|100px\|adxv showing image header info. Pixel size is highlighted]]
	# '''Adjusting JOB Card''' Make a copy of the '''JOB''' line in [[XDS.INP]] for reference. Comment out one line by putting a exclamation mark "!" at the beginning of the line and prepare the other one to run the steps from XYCORR to CORRECT.[[Image:XDS_INP_adjustingJOB.jpeg\|200px\|Adjusting the JOB card in XDS.INP]]		* '''Adjusting JOB Card''' Make a copy of the '''JOB''' line in [[XDS.INP]] for reference. Comment out one line by putting a exclamation mark "!" at the beginning of the line and prepare the other one to run the steps from XYCORR to CORRECT.[[Image:XDS_INP_adjustingJOB.jpeg\|200px\|Adjusting the JOB card in XDS.INP]]
	# '''ORGX and ORGY''' Unless you can guess the direct beam position on the images, ''e.g.'' from ice rings, set both these values to half the detector size. In the case of this example, where the MAR-CCD is 3072x3072 pixels, this means		* '''ORGX and ORGY''' Unless you can guess the direct beam position on the images, ''e.g.'' from ice rings, set both these values to half the detector size. In the case of this example, where the MAR-CCD is 3072x3072 pixels, this means
	ORGX=1536.00 ORGY=1536.00 !Detector origin (pixels).		ORGX=1536.00 ORGY=1536.00 !Detector origin (pixels).
	# '''Experiment specific settings''' The following numbers are also usually found in the image header (or in your lab notebook, or in logs written by the beamline software):		* '''Experiment specific settings''' The following numbers are also usually found in the image header (or in your lab notebook, or in logs written by the beamline software):
	DETECTOR_DISTANCE= 150.0 !(mm)		DETECTOR_DISTANCE= 150.0 !(mm)
	OSCILLATION_RANGE=1.0 !degrees (>0)		OSCILLATION_RANGE=1.0 !degrees (>0)
	X-RAY_WAVELENGTH=1.07176 !Angstroem		X-RAY_WAVELENGTH=1.07176 !Angstroem
	NAME_TEMPLATE_OF_DATA_FRAMES=./images/tutorial_????.img ! TIFF		NAME_TEMPLATE_OF_DATA_FRAMES=./images/tutorial_????.img ! TIFF
	DATA_RANGE=1 180 !Numbers of first and last data image collected		DATA_RANGE=1 180 !Numbers of first and last data image collected
			SPOT_RANGE=1 90 !images to be used for indexing; 1 180 would be better unless there is radiation damage

	Then data processing can start. type <pre>#> xds_par </pre> to run xds and wait until it's finished.		Then data processing can start. type <pre>#> xds_par </pre> to run xds and wait until it's finished.

← Older revision		Revision as of 12:23, 15 March 2011
Line 37:		Line 37:
	!!! ERROR !!! SOLUTION IS INACCURATE		!!! ERROR !!! SOLUTION IS INACCURATE
	Do the following:		Do the following:
	# In IDXREF.LP, find the table '''INDEXING OF OBSERVED SPOTS IN SPACE GROUP'''		* In IDXREF.LP, find the table '''INDEXING OF OBSERVED SPOTS IN SPACE GROUP'''
	*** INDEXING OF OBSERVED SPOTS IN SPACE GROUP # 1 ***		*** INDEXING OF OBSERVED SPOTS IN SPACE GROUP # 1 ***
	16196 OUT OF 76452 SPOTS INDEXED.		16196 OUT OF 76452 SPOTS INDEXED.
Line 48:		Line 48:
	as improved ORGX and ORGY to [[XDS.INP]] and try indexing again.		as improved ORGX and ORGY to [[XDS.INP]] and try indexing again.
	XDS is quite robust and in many cases this approach works		XDS is quite robust and in many cases this approach works
	# Check the refined detector distance		* Check the refined detector distance
	DETECTOR ORIGIN (PIXELS) AT 1514.16 1537.27		DETECTOR ORIGIN (PIXELS) AT 1514.16 1537.27
	CRYSTAL TO DETECTOR DISTANCE (mm) 422.92		CRYSTAL TO DETECTOR DISTANCE (mm) 422.92
	If it deviates by more than 1-2mm from the input distance, check all ~~you~~ parameters again. Is the wavelength really correct, as well as the distance? If you are sure about them, try indexing with only a few images		If it deviates by more than 1-2mm from the input distance, check all your parameters again. Is the wavelength really correct, as well as the distance? If you are sure about them, try indexing with only a few images
	SPOT_RANGE = 1 20		SPOT_RANGE = 1 20