Debian Codegraph @

docs/source/api/getting_started.rst

raw
1 Getting Started
2 -------------------
3
4 This will guide you through several basic tasks using the API, including how
5 to import the API, load settings, and load and save data. Specific file names
6 refer to the RAW Tutorial Data, which you can download. File paths are given
7 from the top level directory of that data.
8
9
10 Importing the API
11 ^^^^^^^^^^^^^^^^^
12
13 Once installed, the RAW API is imported just like any other python package.
14 We recommend that you import just the RAWAPI package, as in the following example.
15
16 .. code-block:: python
17
18 import bioxtasraw.RAWAPI as raw
19
20
21 Loading settings
22 ^^^^^^^^^^^^^^^^^
23
24 Many functions in the API use RAW settings to provide certain parameters for
25 the function (e.g. the calibration parameters and mask used to radially average
26 images). So it is a good idea to load a settings file at the start of your
27 program.
28
29 .. code-block:: python
30
31 my_settings = raw.load_settings('./standards_data/SAXS.cfg')
32
33 While settings can be created and saved using the API, we recommend using the
34 RAW GUI to create and save your settings, then importing them into the API.
35
36
37 Loading data
38 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
39
40 Usually you'll need to start by loading data into your program. Here we
41 show how to load images, profiles, IFTs, and series.
42
43
44 Loading images as scattering profiles
45 ***************************************
46
47 One of the most common tasks is loading images and radially averaging them
48 into 1D scattering profiles. This is easily accomplished with the API.
49
50 .. code-block:: python
51
52 ##Define a list of image filenames to load.
53 buffer_images = ['./standards_data/GIbuf2_A9_18_001_0000.tiff',
54 './standards_data/GIbuf2_A9_18_001_0001.tiff']
55
56 #Load and radially average images
57 profiles, imgs = raw.load_and_integrate_images(buffer_images, my_settings)
58
59 Loading scattering profiles
60 ***************************************
61
62 Another common task is loading data that is already saved as a 1D scattering
63 profile, usually a .dat file.
64
65 .. code-block:: python
66
67 #Define a list of profile filenames to load
68 profile_names = ['./reconstruction_data/glucose_isomerase.dat']
69
70 #Load the profiles
71 profiles = raw.load_profiles(profile_names)
72
73 Loading inverse Fourier transforms (IFTs)
74 ******************************************
75
76 You can use the API to load IFT files containing P(r) functions, either GNOM
77 .out files or .ift files from RAW's BIFT algorithm.
78
79 .. code-block:: python
80
81 #Define a list of IFT filenames to load
82 ift_names = ['./reconstruction_data/gi_complete/glucose_isomerase.out',
83 './reconstruction_data/gi_complete/glucose_isomerase.ift']
84
85 #Load the IFTs
86 ifts = raw.load_ifts(ift_names)
87
88 Loading series
89 ******************
90
91 There are two ways you can load a series. The first is loading a .hdf5 or .sec
92 series file saved by RAW.
93
94 .. code-block:: python
95
96 #Define a list of series filenames to load
97 series_names = ['./series_data/phehc_sec.hdf5', './series_data/xylanase.hdf5']
98
99 #Load the series
100 series = raw.load_series(series_names)
101
102 Alternatively, you can load in all of the individual profiles in the series,
103 then use the API to convert those set of profiles into a series.
104
105 .. code-block:: python
106
107 import glob
108
109 #Define a list of profile filenames to load
110 profile_names = sorted(glob.glob('./series_data/sec_sample_2/BSA_001_*.dat'))
111
112 #Load the profiles
113 profiles = raw.load_profiles(profile_names)
114
115 #Convert the profiles to a series
116 series = raw.profiles_to_series(profiles)
117
118 Note that the input profiles should be in the order they appear in the series.
119
120
121 Working with profiles
122 ^^^^^^^^^^^^^^^^^^^^^^^^
123
124 RAW uses a custom defined class called a SASM (SAS measurement) to contain
125 information about scattering profiles, including the q, I, and uncertainty data
126 as well as metadata data about analysis results.
127
128 Accessing q, I, and uncertainty data
129 ************************************
130
131 RAW SASMs contain several different versions of the q, I, and uncertainty data.
132 Most commonly, you'll want to access the data using the ``getQ()``, ``getI()``
133 and ``getErr()`` functions
134
135 .. code-block:: python
136
137 profile_names = ['./reconstruction_data/glucose_isomerase.dat']
138 profiles = raw.load_profiles(profile_names)
139
140 gi_profile = profiles[0]
141
142 q = gi_profile.getQ()
143 intensity = gi_profile.getI()
144 error = gi_profile.getErr()
145
146 This contains data that has been truncated, scaled and offset according to the
147 profile settings. If you want to access the scaled, offset, and un-truncated
148 data (e.g. without zeros at the beginning skipped for loaded images) you can
149 access ``profile.q``, ``profile.i`` and ``profile.err`` attributes. If there is
150 any truncation, you can get that using ``profile.getQrange()``. So, for example
151
152 .. code-block:: python
153
154 q_range = gi_profile.getQrange()
155
156 gi_profile.getQ() == gi_profile.q[q_range[0]:q_range[1]]
157 gi_profile.getI() == gi_profile.i[q_range[0]:q_range[1]]
158 gi_profile.getErr() == gi_profile.err[q_range[0]:q_range[1]]
159
160 are all true.
161
162 If you want the raw profile data, without any truncation, scaling, or offset,
163 you can use the ``getRawQ()`` ``getRawI()`` and ``getRawErr()`` functions.
164
165 Analyzing the profile
166 **********************
167
168 Many of the RAW analysis functions act on a single scattering profile. For
169 example, to automatically find the best range for the Guinier fit and
170 calculate the Rg and I(0), you can do:
171
172 .. code-block:: python
173
174 guinier_results = raw.auto_guinier(gi_profile)
175
176 Accessing profile metadata
177 ****************************
178
179 The profile saves various bits of metadata to a dictionary. If the profile
180 was created by RAW this includes information on how the profile was created and
181 various metadata parameters from the data collection. It also includes analysis
182 information. To get all of the metadata you can do:
183
184 .. code-block:: python
185
186 metadata = gi_profile.getAllParameters()
187
188 To get a specific category of metadata,
189
190 .. code-block:: python
191
192 analysis = gi_profile.getParameter('analysis')
193
194 guinier_rg = analysis['guinier']['Rg']
195
196
197 Working with IFTs
198 ^^^^^^^^^^^^^^^^^^
199
200 RAW uses a custom defined class called a IFTM (IFT measurement) to contain
201 information about IFTs, including the P(r) function, the fit of the P(r)
202 function to the data, and metadata about the P(r) function.
203
204 Access the P(r) function and fit
205 **********************************
206
207 All of the P(r) data and fit is accessible as attributes of the class.
208
209 .. code-block:: python
210
211 ift_names = ['./reconstruction_data/gi_complete/glucose_isomerase.out']
212 ifts = raw.load_ifts(ift_names)
213
214 gi_ift = ifts[0]
215
216 #Get the P(r) function itself
217 p = gi_ift.p #P(r)
218 r = gi_ift.r
219 err = gi_ift.err #Uncertainty in P(r)
220
221 #Get the original data and the P(r) fit to the original data
222 q = gi_ift.q_orig
223 i = gi_ift.i_orig
224 err = gi_ift.err_orig
225 fit = gi_ift.i_fit
226
227 #Get the fit extrapolated to q=0.
228 q_extrap = gi_ift.q_extrap
229 fit_extrap = gi_ift.i_extrap
230
231 Analyzing the IFT
232 ******************
233
234 There are several functions that take the IFTM as input for analysis, including
235 ambimeter and the various 3D reconstruction methods. Note that analysis methods
236 from the ATSAS package require a GNOM IFT, whereas those natively implemented
237 in RAW (DENSS) work on either GNOM or BIFT IFTs.
238
239 .. code-block:: python
240
241 score, categories, evaluation = raw.ambimeter(gi_ift)
242
243 Accessing IFT metadata
244 ************************
245
246 IFT metadata can be accessed in the same way as for profiles:
247
248 .. code-block:: python
249
250 metadata = gi_ift.getAllParameters()
251
252 dmax = gi_ift.getParameter('dmax')
253
254
255 Working with series
256 ^^^^^^^^^^^^^^^^^^^
257
258 RAW uses a custom defined class called a SECM (SEC measurement, a slightly
259 outdated name) to contain information about series, including the individual
260 scattering profiles, total and mean intensity as a function of frame number,
261 and calculated parameters such as R\ :sub:`g` as a function of frame number.
262
263 Accessing the series data
264 **************************
265
266 In order to visualize the series data it is common to plot total or mean
267 intensity as a function of frame number. You can get that data as:
268
269 .. code-block:: python
270
271 series_names = ['./series_data/baseline.hdf5']
272 series = raw.load_series(series_names)
273
274 my_series = series[0]
275
276 frames = my_series.getFrames()
277 total_i = my_series.getIntI()
278 mean_i = my_series.getMeanI()
279
280 The calculated parameter data is similarly accessed:
281
282 .. code-block:: python
283
284 rg = my_series.getRg()
285 i0 = my_series.getI0()
286 mw_vc = my_series.getVcMW()[0]
287 mw_vp = my_series.getVpMW()[0]
288
289 The intensity for subtracted of baseline corrected data is accessed by specifying
290 the data type
291
292 .. code-block:: python
293
294 subtracted_total_i = my_series.getIntI('sub')
295 subtracted_mean_i = my_series.getMeanI('sub')
296
297 Note that for data with baseline corrected profiles you would use 'baseline'
298
299 If you want to access the underlying profiles, it is done similarly.
300
301 .. code-block:: python
302
303 #Gets all profiles in the series
304 profiles = my_series.getAllSASMs()
305 sub_profiles = my_series.getAllSASMs('sub')
306
307 #Gets a single profile in the series, zero indexed
308 profile_5 = my_series.getSASM(5)
309 sub_profile_5 = my_series.getSASM(5, 'sub')
310
311 #Get profiles from the series in a given range, zero indexed
312 profiles_roi = my_series.getSASMList(10, 20)
313 sub_profiles_roi = my_series.getSASMList(10, 20, 'sub')
314
315 Analyzing the series
316 *********************
317
318 Any analysis you can do on series in the GUI can be done with the API. For
319 example, to automatically find a good buffer region:
320
321 .. code-block:: python
322
323 success, region_start, region_end = raw.find_buffer_range(my_series)
324
325 Accessing series metadata
326 ***************************
327
328 Series in RAW have a lot of associated metadata, such as the buffer range
329 used for subtraction, the start and end of the baseline correction ranges,
330 or the sample range. Most of these are accessible as attributes of the SECM.
331
332 .. code-block:: python
333
334 buffer_range = my_series.buffer_range
335 sample_range = my_series.sample_range
336
337
338 Saving data
339 ^^^^^^^^^^^^^^^
340
341 After you process your data you will want to save it. Here we show how to save
342 profiles, IFTs, and series.
343
344 Saving scattering profiles
345 ***************************
346
347 Suppose you have the scattering profile ``my_profile``. You would save the
348 profile as:
349
350 .. code-block:: python
351
352 raw.save_profile(my_profile, 'my_profile.dat', './my_profile_dir')
353
354 Saving inverse Fourier transforms (IFTs)
355 ********************************************
356
357 Suppose you have the IFT ``my_ift``. You would save the IFT as:
358
359 .. code-block:: python
360
361 raw.save_ift(my_ift, 'my_ift.out', './my_ift_dir')
362
363 Note that you use the ``.out`` extension for GNOM IFTs, and the ``.ift``
364 extension for BIFT IFTs.
365
366 Saving series
367 **************
368
369 Suppose you have the series ``my_series``. You would save the series as:
370
371 .. code-block:: python
372
373 raw.save_series(my_series, 'my_series.hdf5', './my_series_dir')