analyse

(1) spipy.analyse.q

+ :numpy.1darray = cal_q (detd:float, lamda:float, det_r:int, pixsize:int)

+ :numpy.1darray = cal_r (qlist:numpy.1darray, detd:float, lamda:float, det_r:int, pixsize:int)

+ :float = oversamp_rate (sample_size:float, detd:float, lamda:float, det_r:int, pixsize:int)

--

• cal_q : calculate frequency q values, also known as k'-k
  • detd : distance between detector and sample, unit=mm
  • lamda : wave length, unit=Angstrom
  • det_r : the highest resolution (radius on detector) that you want to calculate to, unit=pixels
  • pixsize : physical length of a detector pixel, unit=mm

--

• cal_r : calculate radius list on detector corresponding to a q-list
  • qlist : input q list, numpy.ndarray, shape=(Nq,)

--

• oversamp_rate : calculate oversampling rate
  • sample_size : diameter of your experiment sample， unit=nm
  • detd : distance between detector and sample, unit=mm
  • det_r : the highest resolution (radius on detector) that you want to calculate to, unit=pixels
  • pixsize : physical length of a detector pixel, unit=mm

(2) spipy.analyse.saxs

+ :(numpy.ndarray, ...) = grid (input_patt:numpy.ndarray)

+ :numpy.1darray = frediel_search (pattern:numpy.2darray, estimated_center:(int, int), #mask:numpy.2darray/None)

+ :numpy.1darray = inten_profile_vaccurate (dataset:numpy.3darray, mask:numpy.2darray, *exp_param:[...])

+ :numpy.1darray = inten_profile_vfast (dataset:numpy.3darray, mask:numpy.2darray, *exp_param:[...])

+ :numpy.2darray = cal_saxs (data:numpy.3darray)

+ :[numpy.2darray, numpy.2darray] = centering (pat:numpy.2darray, estimated_center:list or array, #mask:numpy.2darray/None)

+ :[float, numpy.1darray] = particle_size (saxs:numpy.2darray, estimated_center:list or array, #exparam:str/None, #high_filter_cut:float/0.3, #power:float/0.7, #mask:numpy.2darray/None)

--

• grid : return x and y indices of a pattern/volume
  • input_patt : input pattern or volume. If it is a pattern, then returned value consists two 2d-arrays, one is the x coordinates of every pixels, and the other is y coordinates. If input is a scattering volume, then returned value consists 3 3d-arrays.

--

• frediel_search : return the center point (zero frequency) of a pattern, numpy.array([Cx,Cy])
  • pattern : input pattern. Check there is no nan or inf values.
  • estimated_center : an estimated center, (Cx',Cy'), the max deviation between estimated and real center should be less than 20 pixels
  • #mask : 0/1 binary pattern, shape=(Nx, Ny), 1 means masked area, 0 means useful area, default=None

--

• inten_profile_vaccurate : return the averaged intensity radial profile. shape=(2,Nq), the first colum is q value while the second one is radial intensities. This function processes every image so it is more accurate, but PRETTY SLOW
  • dataset : patterns, shape=(Nd,Nx,Ny)
  • mask : 0/1 binary pattern, shape=(Nx, Ny), 1 means masked area, 0 means useful area, set None to ignore
  • *exp_param : for calculating q value, please give all experiment parameters required in spipy.analyse.q.cal_q

--

• inten_profile_vfast : fast calculation of intensity profile, RECOMENDED
  • [The same parameters with inten_profile_vaccurate]

--

• cal_saxs : return averging pattern of a pattern set
  • data : input pattern set, shape=(Nd,Nx,Ny)

--

• centering : shift the input pattern to its center, output pattern is a part of original one. The output is a list [newpat : a numpy.2darray with shape=(Nx',Ny'), newmask : output mask with shape=(Nx'Ny')]
  • pat : input pattern, shape=(Nx,Ny)
  • estimated_center : the estimated center of original pattern, see its requirements in frediel_search function
  • #mask : 0/1 binary pattern, shape=(Nx, Ny), 1 means masked area, 0 means useful area, default=None

--

• particle_size : estimate particle size through saxs pattern, this function uses self-correlation transformation method to estimate particle size. Output is a list, [ particle_size (float), auto_correlation_radial_profile (2darray) ]
  • saxs : input saxs pattern, 2darray shape=(Nx,Ny)
  • estimated_center : estimated center of saxs pattern, list or array (Cx,Cy)
  • #exparam : experimental parameters, str, 'detector-sample distance(mm),lambda(A),pixel length(mm)', such as '578,7.9,0.3', default=None
  • #high_filter_cut : float between (0,1), which determine the FWHM of high pass filter, larger value means smaller filter width, default=0.3
  • #power : positive float 0~1, a power conducted on pattern to enhance the contribution of high q data, default=0.7
  • #mask : 0/1 binary pattern, shape=(Nx, Ny), 1 means masked area, 0 means useful area, default=None
  • [NOTICE] RECOMMOND to watch auto-correlation radial profile and find the locations of peaks, which are most trustable values of possible particle sizes. auto_correlation_radial_profile is a 2-d array, where the 1st colum is particle size in nm (if exparam is given) and 2nd colum is the auto-correlation value.
  • [NOTICE] if your give exparam, the output particle_size is in nanometer; otherwise it is in pixels.

(3) spipy.analyse.orientation

+ :[numpy.2darray, numpy.2darray] = Sphere_randp (algo:str, radius:float, num:int)

+ :[numpy.2darray, numpy.2darray] = proc_Hammer (qlist:numpy.2darray, data:numpy.1darray)

+ :void = draw_Hammer (logi_lati:numpy.2darray, #save_dir:str/None) 

+ :void = draw_ori_Df (ori_bin:str, q_level:int)

--

• Sphere_randp : return random/uniform distributed points on a pherical surface, shape=[np.numpy(Np,3), np.numpy(Np,2)]
  • algo : algorithm, string "random" or "uniform"
  • radius : radius of the sphere, unit=pixels
  • num : numbers of points you want to generate

--

• proc_Hammer : transfer quaternions to Aitoff-Hammer projection coordinates, return [ numpy.array( [ logitute[..], latitute[..], value[..] ] ), numpy.array( [ x[..], y[..], value[..] ] ) ]
  • qlist : quaternion list, numpy.array( [ w[..], qx[..], qy[..], qz[..] ] ); or xyz coordinates, numpy.array( [ x[..], y[..], z[..] ] ). That is, shape=(Nq, 4) or (Nq,3)
  • [Notice] w = cos(the/2) , q? = ? * sin(theta/2). BE CAREFUL of the order!
  • data : the corresponding value for every quaternion (orientation), this function do not care what these values really mean. shape=(Nq,1)

--

• draw_Hammer : draw figure to show distribution of quaternions with corresponding values
  • logi_lati : Logitute, latitute and value, shape=(Nq,3) ( The first output of proc_Hammer )
  • #save_dir : string, the path if you want to save figure. default is None

--

• draw_ori_Df : draw figure to show orientation distribution of DragonFly output
  • ori_bin : string, path of output 'orientation_xxx.bin' file from spipy.merge.emc
  • q_level : the 'num_div' parameter used in spipy.merge.emc

(4) spipy.analyse.SH_expan

+ :numpy.1darray = sp_hamonics (data:{'volume':numpy.3darray, 'mask':numpy.3darray}, r:float, #L:int/10)

--

• sp_harmonics : spherical harmonics expansion of a 3D model, return Cl, shape=(L,)
  • data : { 'volume' : intensity voxel data, 'mask' : mask voxel data }, if no mask please set 'mask' : None
  • r : radius of the shell you want to expand, unit=pixels
  • #L : level of hamonics, recommended >=10, default=10

(5) spipy.analyse.criterion

+ :float = r_factor (F_cal:numpy.3darray, F_obs:numpy.3darray)

+ :numpy.1darray = r_factor_shell (F_cal:numpy.3darray, F_obs:numpy.3darray, rlist:list/np.1darray)

+ :numpy.1darray = fsc (F1:numpy.3darray, F2:numpy.3darray, rlist:list or array)

+ :numpy.1darray = r_split (F1:numpy.3darray, F2:numpy.3darray, rlist:list or array)

--

• r_factor : overall r-factor of two models, return a float~[0,1]
  • F_cal : voxel models from calculation
  • F_obs : voxel models from observation

--

• r_factor_shell : r-factor of shells with different radius between two models, return an array containing r-factors of all shells
  • F_cal : voxel models from calculation
  • F_obs : voxel models from observation
  • rlist : radius list of shells

--

• fsc : Fourier Shell Correlation between two models (in frequency space), return an array containing correlations of all shells
  • F1 : the first voxel model
  • F2 : the second voxel model
  • rlist : radius list of shells

--

• r_split : r-split factors between two models (in frequency space), return r-split ,an numpy array, the same shape with rlist
  • F1 : the first voxel model
  • F2 : the second voxel model
  • rlist : radius list of shells

(6) spipy.analyse.rotate

+ :numpy.2darray = eul2rotm (ea:list/np.1darray, order:str)

+ :numpy.3darray = rot_ext (ea:list/nump.1darray, order:str, matrix:numpy.3darray, #ref:numpy.3darray/None)

+ :(float, list, numpy.3darray) = align (fix:numpy.3darray, mov:numpy.3darray, #grid_unit:list/[0.3,0.1], #nproc:int/2, #resize:int/40, #order:str/'zxz')

--

• eul2rotm : transfer euler angles to rotation matrix in intrinsic order, return 3x3 rotation matrix
  • ea : euler angles, intrinsic rotation, unit = rad
  • order : rotation order, such as 'zxz', 'zyz' or 'xyz'

--

• rot_ext : do an extrinsic rotation to a 3D voxel model, return rotated model
  • ea : euler angles, extrinsic rotation, unit = rad
  • order : rotation order, such as 'zxz', 'zyz', 'xyz'
  • matrix : input voxel model in 3d matrix
  • #ref : reference model in 3d matrix, if given, program will compare rotated model with reference by ploting their x/y/z slices. default is None

--

• align : Using grid search (euler angles) to align two models, return (r_factor : overall r-factor between fixed and best aligned mov model , ea : best aligned euler angle , new_mov : mov model after aligned)
  • fix : fixed model
  • mov : rotated model while aligning
  • #grid_unit : grid size (in rad) of alpha,beta,gamma euler angles. This is a list, default=[0.3, 0.1], which means the program will firstly search with grid_size = 0.3 rad, then fine-tune around the euler angles it just gets that best align two models with smaller grid_size (= 0.1 rad). Of course you can use more loops such as [0.3, 0.1, 0.02, ...]
  • #nproc : number of processes to run in parallel, NOTE that the program parallels in alpha angles, default=2
  • #resize : resize your input models to a smaller size to accelerate, default=40 pixels
  • #order : rotation order while aligning, default='zxz'
  • [NOTICE] range of three euler angles : alpha [0, 2pi); beta [0, pi); gamma [0, 2pi)