Getting Started ------------------- This will guide you through several basic tasks using the API, including how to import the API, load settings, and load and save data. Specific file names refer to the RAW Tutorial Data, which you can download. File paths are given from the top level directory of that data. Importing the API ^^^^^^^^^^^^^^^^^ Once installed, the RAW API is imported just like any other python package. We recommend that you import just the RAWAPI package, as in the following example. .. code-block:: python import bioxtasraw.RAWAPI as raw Loading settings ^^^^^^^^^^^^^^^^^ Many functions in the API use RAW settings to provide certain parameters for the function (e.g. the calibration parameters and mask used to radially average images). So it is a good idea to load a settings file at the start of your program. .. code-block:: python my_settings = raw.load_settings('./standards_data/SAXS.cfg') While settings can be created and saved using the API, we recommend using the RAW GUI to create and save your settings, then importing them into the API. Loading data ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Usually you'll need to start by loading data into your program. Here we show how to load images, profiles, IFTs, and series. Loading images as scattering profiles *************************************** One of the most common tasks is loading images and radially averaging them into 1D scattering profiles. This is easily accomplished with the API. .. code-block:: python ##Define a list of image filenames to load. buffer_images = ['./standards_data/GIbuf2_A9_18_001_0000.tiff', './standards_data/GIbuf2_A9_18_001_0001.tiff'] #Load and radially average images profiles, imgs = raw.load_and_integrate_images(buffer_images, my_settings) Loading scattering profiles *************************************** Another common task is loading data that is already saved as a 1D scattering profile, usually a .dat file. .. code-block:: python #Define a list of profile filenames to load profile_names = ['./reconstruction_data/glucose_isomerase.dat'] #Load the profiles profiles = raw.load_profiles(profile_names) Loading inverse Fourier transforms (IFTs) ****************************************** You can use the API to load IFT files containing P(r) functions, either GNOM .out files or .ift files from RAW's BIFT algorithm. .. code-block:: python #Define a list of IFT filenames to load ift_names = ['./reconstruction_data/gi_complete/glucose_isomerase.out', './reconstruction_data/gi_complete/glucose_isomerase.ift'] #Load the IFTs ifts = raw.load_ifts(ift_names) Loading series ****************** There are two ways you can load a series. The first is loading a .hdf5 or .sec series file saved by RAW. .. code-block:: python #Define a list of series filenames to load series_names = ['./series_data/phehc_sec.hdf5', './series_data/xylanase.hdf5'] #Load the series series = raw.load_series(series_names) Alternatively, you can load in all of the individual profiles in the series, then use the API to convert those set of profiles into a series. .. code-block:: python import glob #Define a list of profile filenames to load profile_names = sorted(glob.glob('./series_data/sec_sample_2/BSA_001_*.dat')) #Load the profiles profiles = raw.load_profiles(profile_names) #Convert the profiles to a series series = raw.profiles_to_series(profiles) Note that the input profiles should be in the order they appear in the series. Working with profiles ^^^^^^^^^^^^^^^^^^^^^^^^ RAW uses a custom defined class called a SASM (SAS measurement) to contain information about scattering profiles, including the q, I, and uncertainty data as well as metadata data about analysis results. Accessing q, I, and uncertainty data ************************************ RAW SASMs contain several different versions of the q, I, and uncertainty data. Most commonly, you'll want to access the data using the ``getQ()``, ``getI()`` and ``getErr()`` functions .. code-block:: python profile_names = ['./reconstruction_data/glucose_isomerase.dat'] profiles = raw.load_profiles(profile_names) gi_profile = profiles[0] q = gi_profile.getQ() intensity = gi_profile.getI() error = gi_profile.getErr() This contains data that has been truncated, scaled and offset according to the profile settings. If you want to access the scaled, offset, and un-truncated data (e.g. without zeros at the beginning skipped for loaded images) you can access ``profile.q``, ``profile.i`` and ``profile.err`` attributes. If there is any truncation, you can get that using ``profile.getQrange()``. So, for example .. code-block:: python q_range = gi_profile.getQrange() gi_profile.getQ() == gi_profile.q[q_range[0]:q_range[1]] gi_profile.getI() == gi_profile.i[q_range[0]:q_range[1]] gi_profile.getErr() == gi_profile.err[q_range[0]:q_range[1]] are all true. If you want the raw profile data, without any truncation, scaling, or offset, you can use the ``getRawQ()`` ``getRawI()`` and ``getRawErr()`` functions. Analyzing the profile ********************** Many of the RAW analysis functions act on a single scattering profile. For example, to automatically find the best range for the Guinier fit and calculate the Rg and I(0), you can do: .. code-block:: python guinier_results = raw.auto_guinier(gi_profile) Accessing profile metadata **************************** The profile saves various bits of metadata to a dictionary. If the profile was created by RAW this includes information on how the profile was created and various metadata parameters from the data collection. It also includes analysis information. To get all of the metadata you can do: .. code-block:: python metadata = gi_profile.getAllParameters() To get a specific category of metadata, .. code-block:: python analysis = gi_profile.getParameter('analysis') guinier_rg = analysis['guinier']['Rg'] Working with IFTs ^^^^^^^^^^^^^^^^^^ RAW uses a custom defined class called a IFTM (IFT measurement) to contain information about IFTs, including the P(r) function, the fit of the P(r) function to the data, and metadata about the P(r) function. Access the P(r) function and fit ********************************** All of the P(r) data and fit is accessible as attributes of the class. .. code-block:: python ift_names = ['./reconstruction_data/gi_complete/glucose_isomerase.out'] ifts = raw.load_ifts(ift_names) gi_ift = ifts[0] #Get the P(r) function itself p = gi_ift.p #P(r) r = gi_ift.r err = gi_ift.err #Uncertainty in P(r) #Get the original data and the P(r) fit to the original data q = gi_ift.q_orig i = gi_ift.i_orig err = gi_ift.err_orig fit = gi_ift.i_fit #Get the fit extrapolated to q=0. q_extrap = gi_ift.q_extrap fit_extrap = gi_ift.i_extrap Analyzing the IFT ****************** There are several functions that take the IFTM as input for analysis, including ambimeter and the various 3D reconstruction methods. Note that analysis methods from the ATSAS package require a GNOM IFT, whereas those natively implemented in RAW (DENSS) work on either GNOM or BIFT IFTs. .. code-block:: python score, categories, evaluation = raw.ambimeter(gi_ift) Accessing IFT metadata ************************ IFT metadata can be accessed in the same way as for profiles: .. code-block:: python metadata = gi_ift.getAllParameters() dmax = gi_ift.getParameter('dmax') Working with series ^^^^^^^^^^^^^^^^^^^ RAW uses a custom defined class called a SECM (SEC measurement, a slightly outdated name) to contain information about series, including the individual scattering profiles, total and mean intensity as a function of frame number, and calculated parameters such as R\ :sub:`g` as a function of frame number. Accessing the series data ************************** In order to visualize the series data it is common to plot total or mean intensity as a function of frame number. You can get that data as: .. code-block:: python series_names = ['./series_data/baseline.hdf5'] series = raw.load_series(series_names) my_series = series[0] frames = my_series.getFrames() total_i = my_series.getIntI() mean_i = my_series.getMeanI() The calculated parameter data is similarly accessed: .. code-block:: python rg = my_series.getRg() i0 = my_series.getI0() mw_vc = my_series.getVcMW()[0] mw_vp = my_series.getVpMW()[0] The intensity for subtracted of baseline corrected data is accessed by specifying the data type .. code-block:: python subtracted_total_i = my_series.getIntI('sub') subtracted_mean_i = my_series.getMeanI('sub') Note that for data with baseline corrected profiles you would use 'baseline' If you want to access the underlying profiles, it is done similarly. .. code-block:: python #Gets all profiles in the series profiles = my_series.getAllSASMs() sub_profiles = my_series.getAllSASMs('sub') #Gets a single profile in the series, zero indexed profile_5 = my_series.getSASM(5) sub_profile_5 = my_series.getSASM(5, 'sub') #Get profiles from the series in a given range, zero indexed profiles_roi = my_series.getSASMList(10, 20) sub_profiles_roi = my_series.getSASMList(10, 20, 'sub') Analyzing the series ********************* Any analysis you can do on series in the GUI can be done with the API. For example, to automatically find a good buffer region: .. code-block:: python success, region_start, region_end = raw.find_buffer_range(my_series) Accessing series metadata *************************** Series in RAW have a lot of associated metadata, such as the buffer range used for subtraction, the start and end of the baseline correction ranges, or the sample range. Most of these are accessible as attributes of the SECM. .. code-block:: python buffer_range = my_series.buffer_range sample_range = my_series.sample_range Saving data ^^^^^^^^^^^^^^^ After you process your data you will want to save it. Here we show how to save profiles, IFTs, and series. Saving scattering profiles *************************** Suppose you have the scattering profile ``my_profile``. You would save the profile as: .. code-block:: python raw.save_profile(my_profile, 'my_profile.dat', './my_profile_dir') Saving inverse Fourier transforms (IFTs) ******************************************** Suppose you have the IFT ``my_ift``. You would save the IFT as: .. code-block:: python raw.save_ift(my_ift, 'my_ift.out', './my_ift_dir') Note that you use the ``.out`` extension for GNOM IFTs, and the ``.ift`` extension for BIFT IFTs. Saving series ************** Suppose you have the series ``my_series``. You would save the series as: .. code-block:: python raw.save_series(my_series, 'my_series.hdf5', './my_series_dir')