FreeSAS Package

This is the public API of FreeSAS. Since most of the number crunching part is implemented in Cython, it is not documented here: please refer to the source code.

freesas.align

freesas.autorg

freesas.average

freesas.bift

freesas.collections

Set of namedtuples defined a bit everywhere

class RG_RESULT(Rg, sigma_Rg, I0, sigma_I0, start_point, end_point, quality, aggregated)

Bases: tuple

I0

Alias for field number 2

Rg

Alias for field number 0

aggregated

Alias for field number 7

end_point

Alias for field number 5

quality

Alias for field number 6

sigma_I0

Alias for field number 3

sigma_Rg

Alias for field number 1

start_point

Alias for field number 4

class FIT_RESULT(slope, sigma_slope, intercept, sigma_intercept, R, R2, chi2, RMSD)

Bases: tuple

R

Alias for field number 4

R2

Alias for field number 5

RMSD

Alias for field number 7

chi2

Alias for field number 6

intercept

Alias for field number 2

sigma_intercept

Alias for field number 3

sigma_slope

Alias for field number 1

slope

Alias for field number 0

class RT_RESULT(Vc, sigma_Vc, Qr, sigma_Qr, mass, sigma_mass)

Bases: tuple

Qr

Alias for field number 2

Vc

Alias for field number 0

mass

Alias for field number 4

sigma_Qr

Alias for field number 3

sigma_Vc

Alias for field number 1

sigma_mass

Alias for field number 5

class RadiusKey(Dmax, npt)

Bases: tuple

Dmax

Alias for field number 0

npt

Alias for field number 1

class PriorKey(type, npt)

Bases: tuple

npt

Alias for field number 1

type

Alias for field number 0

class TransfoValue(transfo, B, sum_dia)

Bases: tuple

B

Alias for field number 1

sum_dia

Alias for field number 2

transfo

Alias for field number 0

class EvidenceKey(Dmax, alpha, npt)

Bases: tuple

Dmax

Alias for field number 0

alpha

Alias for field number 1

npt

Alias for field number 2

class EvidenceResult(evidence, chi2r, regularization, radius, density, converged)

Bases: tuple

chi2r

Alias for field number 1

converged

Alias for field number 5

density

Alias for field number 4

evidence

Alias for field number 0

radius

Alias for field number 3

regularization

Alias for field number 2

class StatsResult(radius, density_avg, density_std, evidence_avg, evidence_std, Dmax_avg, Dmax_std, alpha_avg, alpha_std, chi2r_avg, chi2r_std, regularization_avg, regularization_std, Rg_avg, Rg_std, I0_avg, I0_std)

Bases: tuple

Dmax_avg

Alias for field number 5

Dmax_std

Alias for field number 6

I0_avg

Alias for field number 15

I0_std

Alias for field number 16

Rg_avg

Alias for field number 13

Rg_std

Alias for field number 14

alpha_avg

Alias for field number 7

alpha_std

Alias for field number 8

chi2r_avg

Alias for field number 9

chi2r_std

Alias for field number 10

density_avg

Alias for field number 1

density_std

Alias for field number 2

evidence_avg

Alias for field number 3

evidence_std

Alias for field number 4

radius

Alias for field number 0

regularization_avg

Alias for field number 11

regularization_std

Alias for field number 12

save(filename, source=None)

Save the results of the fit to the file

save_bift(stats, filename, source=None)[source]

Save the results of the fit to the file

class GOF(n, c, P)

Bases: tuple

P

Alias for field number 2

c

Alias for field number 1

n

Alias for field number 0

freesas.cormap

class LongestRunOfHeads[source]

Bases: object

Implements the “longest run of heads” by Mark F. Schilling The College Mathematics Journal, Vol. 21, No. 3, (1990), pp. 196-207

See: http://www.maa.org/sites/default/files/pdf/upload_library/22/Polya/07468342.di020742.02p0021g.pdf

A(n, c)[source]

Calculate A(number_of_toss, length_of_longest_run)

Parameters:
  • n – number of coin toss in the experiment, an integer
  • c – length of the longest run of
Returns:

The A parameter used in the formula

B(n, c)[source]

Calculate B(number_of_toss, length_of_longest_run) to have either a run of Heads either a run of Tails

Parameters:
  • n – number of coin toss in the experiment, an integer
  • c – length of the longest run of
Returns:

The B parameter used in the formula

probaHeadOrTail(n, c)[source]

Calculate the probability of a longest run of head or tails to occur

Parameters:
  • n – number of coin toss in the experiment, an integer
  • c – length of the longest run of heads or tails, an integer
Returns:

The probablility of having c subsequent heads or tails in a n toss of fair coin

probaLongerRun(n, c)[source]

Calculate the probability for the longest run of heads or tails to exceed the observed length

Parameters:
  • n – number of coin toss in the experiment, an integer
  • c – length of thee observed run of heads or tails, an integer
Returns:

The probablility of having more than c subsequent heads or tails in a n toss of fair coin

gof(data1, data2)[source]

Calculate the probability for a couple of dataset to be equivalent

Implementation according to: http://www.nature.com/nmeth/journal/v12/n5/full/nmeth.3358.html

Parameters:
  • data1 – numpy array
  • data2 – numpy array
Returns:

probablility for the 2 data to be equivalent

freesas.invariants

This module is mainly about the calculation of the Rambo-Tainer invariant described in:

https://dx.doi.org/10.1038%2Fnature12070

Some formula taken from Putnam et al, 2007, Table 1 in the review

extrapolate(data, guinier)[source]

Extrapolate SAS data according to the Guinier fit until q=0 Uncertainties are extrapolated (linearly) from the Guinier region

Parameters:
  • data – SAS data in q,I,dI format
  • guinier – result of a Guinier fit
Returns:

extrapolated SAS data

calc_Porod(data, guinier)[source]

Calculate the particle volume according to Porod’s formula:

V = 2*π²I₀²/(sum_q I(q)q² dq)

Formula from Putnam’s review, 2007, table 1 Intensities are extrapolated to q=0 using Guinier fit.

Parameters:
  • data – SAS data in q,I,dI format
  • Guinier – result of a Guinier fit (instance of RT_RESULT)
Returns:

Volume calculated according to Porrod’s formula

calc_Vc(data, Rg, dRg, I0, dI0, imin)[source]

Calculates the Rambo-Tainer invariant Vc, including extrapolation to q=0

Parameters:
  • data – SAS data in q,I,dI format, cropped to maximal q that should be used for calculation (normally 2 nm-1)
  • Rg,dRg,I0,dI0 – results from Guinier approximation/autorg
  • imin – minimal index of the Guinier range, below that index data will be extrapolated by the Guinier approximation
Returns:

Vc and an error estimate based on non-correlated error propagation

calc_Rambo_Tainer(data, guinier, qmax=2.0)[source]

calculates the invariants Vc and Qr from the Rambo & Tainer 2013 Paper, also the the mass estimate based on Qr for proteins

Parameters:
  • data – data in q,I,dI format, q in nm^-1
  • guinier – RG_RESULT instance with result from the Guinier fit
  • qmax – maximum q-value for the calculation in nm^-1

@return: dict with Vc, Qr and mass plus errors

freesas.model

freesas.plot

Functions to generating graphs related to SAS.

scatter_plot(data, guinier=None, ift=None, filename=None, img_format='svg', unit='nm', title='Scattering curve', ax=None, labelsize=None, fontsize=None)[source]

Generate a scattering plot I = f(q) in semi_log_y.

Parameters:
  • data – data read from an ASCII file, 3 column (q,I,err)
  • filename – name of the file where the cuve should be saved
  • img_format – image format
  • unit – Unit name for Rg and 1/q
  • guinier – output of autoRg
  • ift – converged instance of BIFT (output of auto_bift)
  • ax – subplot where the plot shall go in
Returns:

the matplotlib figure

kratky_plot(data, guinier, filename=None, img_format='svg', unit='nm', title='Dimensionless Kratky plot', ax=None, labelsize=None, fontsize=None)[source]

Generate a Kratky plot q²Rg²I/I₀ = f(q·Rg)

Parameters:
  • data – data read from an ASCII file, 3 column (q,I,err)
  • guinier – output of autoRg
  • filename – name of the file where the cuve should be saved
  • img_format – image format
  • unit – Unit name for Rg and 1/q
  • ax – subplot where the plot shall go in
Returns:

the matplotlib figure

guinier_plot(data, guinier, filename=None, img_format='png', unit='nm', ax=None, labelsize=None, fontsize=None)[source]

Generate a guinier plot: ln(I) = f(q²)

Parameters:
  • data – data read from an ASCII file, 3 column (q,I,err)
  • guinier – A RG_RESULT object from AutoRg
  • filename – name of the file where the cuve should be saved
  • img_format – image format
Param:

ax: subplot where to plot in

Returns:

the matplotlib figure

density_plot(ift, filename=None, img_format='png', unit='nm', ax=None, labelsize=None, fontsize=None)[source]

Generate a density plot p(r)

@param ift: An IFT result comming out of BIFT @param filename: name of the file where the cuve should be saved @param img_format: image image format @param ax: subplotib where to plot in @return: the matplotlib figure

plot_all(data, filename=None, img_format=None, unit='nm', labelsize=None, fontsize=None)[source]

freesas.sasio

Contains helper functions for loading SAS data from differents sources.

load_scattering_data(filename: Union[os.PathLike, str, bytes]) → numpy.ndarray[source]

Load scattering data q, I, err into a numpy array.

Parameters:filename – ASCII file, 3 column (q,I,err)
Returns:numpy array with 3 column (q,I,err)
parse_ascii_data(input_file_text: List[str], number_of_columns: int) → numpy.ndarray[source]

Parse data from an ascii file into an N column numpy array

Parameters:
  • input_file_text – List containing one line of input data per element
  • number_of_columns – Expected number of lines in the data file
Returns:

numpy array with 3 column (q,I,err)

convert_inverse_angstrom_to_nanometer(data_in_inverse_angstrom: numpy.ndarray) → numpy.ndarray[source]

Convert data with q in 1/Å to 1/nm.

Parameters:data_in_inverse_angstrom – numpy array in format (q_in_inverse_Angstrom,I,err)
Returns:numpy array with 3 column (q_in_inverse_nm,I,err)