SanXoT
SanXoT v2.13 is the central program of the SanXoT Software Package developed in the Jesus Vazquez Cardiovascular Proteomics Lab at Centro Nacional de Investigaciones Cardiovasculares, used to perform integration of experimental data to a higher level (such as integration from peptide data to protein data), while determining the variance between them.
SanXoT needs two input files:
- the lower level input data file, a tab separated text file containing three columns: the first one with the unique identifiers of each lower level element (such as "RawFile05.raw-scan19289-charge2" for a scan, or "CGLAGCGLLK" for a peptide sequence, or "P01308" for the Uniprot accession number of a protein), the Xi which corresponds to the log2(A/B), and the Vi which corresponds to the weight of the measure). This data have to be pre-calibrated with a certain weight (see help of the Klibrate program).
- the relations file, a tab separated text file containing a first column with the higher level identifiers (such as the peptide sequence, a Uniprot accession number, or a Gene Ontology category) and the lower level identifiers within the abovementioned input data file.
- NOTE: you must include a first line header in all your files.
And delivers six output files:
- the output data file for the higher level, which has the same format as the lower level data file, but containing the ids of the higher level in the first column, the ratio Xj in the second column, and the weight Vj in the third column. By default, this file is suffixed as "_higherLevel".
- two lower level output files, containing three columns each: in both, the first column contains with the identifiers of the lower level, the second column contains the Xinf - Xsup (i.e. the ratios of the lower level, but centered for each element they belong to), and the third column is either the new weight Winf (contanining the variance of the integration) or the former untouched Vinf weight. For example, integrating from scan to peptide, these files would contain firstly the scan identifiers, secondly the Xscan - Xpep (the ratios of each scan compared to the peptide they are identifying) and either Wscan (the weight of the scan, taking into account the variance of the scan distribution) or Vscan. By default, these files are suffixed "_lowerNormW" and "_lowerNormV".
- a file useful for statistics, containing all the relations of the higher and lower level element present in the data file, with a copy of their ratios X and weights V, followed by the number of lower elements contained in the upper element (for example, the number of scans that identify the same peptide), the Z (which is the distance in sigmas of the lower level ratio X to the higher level weighted average), and the FDR (the false discovery rate, important to keep track of changes or outliers). By default, this file is suffixed "_outStats".
- an info file, containing a log of the performed integrations. Its last line is always in the form of "Variance = [double]". This file can be used as input in place of the variance (see -v and -V arguments). By default, this file is suffixed "_infoFile".
- a graph file, depicting the sigmoid of the Z column which appears in the stats file, compared to the theoretical normal distribution. By default, this file is suffixed "_outGraph".
Usage:
sanxot.py -d[data file] -r[relations file] [OPTIONS]
Arguments:
-h, --help Display basic help and exit.
-H, --advanced-help Display this help and exit.
-A, --outrandom=filename
To use a non-default name for the randomised relations
file (only applicable when -R is in use).
-a, --analysis=string
Use a prefix for the output files. If this is not
provided, then the prefix will be garnered from the data
file.
-b, --no-verbose Do not print result summary after executing.
-C, --confluence A modified version of the relations file is used, where
all the destination higher level elements are "1". If no
relations file is provided, the program gets the lower
level elements from the first column of the data file.
-d, --datafile=filename
Data file with identificators of the lowel level in the
first column, measured values (x) in the second column,
and weights (v) in the third column.
-D, --removeduplicateupper
When merging data with relations table, remove duplicate
higher level elements (not removed by default).
-f, --forceparameters
Use the parameters as provided, without using the
Levenberg-Marquardt algorithm. Negative variances will
be reset to zero (see -F if you do not wish this).
-F, --forcenegativevariance
Though the indirect calculation of variance may lead to
a negative value, this has no mathematical meaning and
may cause a number of artefacts; hence, by default,
negative variances are automatically reset to zero.
However, for some analyses, it might be important seeing
the effect of original variance; for these cases, use
this option to override resetting negative variances to
zero.
-g, --no-graph Do not show the Zij vs rank / N graph.
-G, --outgraph=filename
To use a non-default name for the graph file.
-J, --includeorphans
In the case all the lower elements pointing to a higher
level element are excluded, the default behaviour is
removing the higher level element altogether. Adding
this option, the lower level elements will be integrated
in any case.
-l, --graphlimits=integer
To set the +- limits of the Zij graph (default is 6). If
you want the limits to be between the minimum and
maximum values, you can use -l.
-L, --infofile=filename
To use a non-default name for the info file.
-m, --maxiterations=integer
Maximum number of iterations performed by the Levenberg-
Marquardt algorithm to calculate the variance. If
unused, then the default value of the algorithm is
taken.
-M, --minseed=float To use a non-default minimum seed. Default is 1e-3.
-o, --higherlevel=filename
To use a non-default higher level output file name.
-p, --place, --folder=foldername
To use a different common folder for the output files.
If this is not provided, the the folder used will be the
same as the input folder.
-r, --relfile, --relationsfile=filename
Relations file, with identificators of the higher level
in the first column, and identificators of the lower
level in the second column.
-R, --randomise, --randomize
A modified version of the relations file is used, where
the higher level elements (first column) are replaced by
numbers and randomly written in the first column. The
numbers range from 1 to the total number of elements.
The second column (containing the lowel level elements)
remains unchanged.
-s, --no-steps Do not print result summary and the steps of every
Levenberg-Marquardt iteration.
-t, --graphtitle=string
The graph title (default is
"Zij graph for sigma^2 = [variance]").
-T, --minimalgraphticks
It will only show the x secondary line for x = 0, and
none for the Y axis (useful for publishing).
-u, --lowernormw=filename
To use a non-default lower level output file name,
setting W as weight (default suffix is _lowerNormW).
-U, --lowernormv=filename
To use a non-default lower level output file name,
setting V as weight (default suffix is _lowerNormV).
-v, --var, --varianceseed=double
Seed used to start calculating the variance.
Default is 0.001.
-V, --varfile=filename
Get the variance value from a text file. It must contain
a line (not more than once) with the text
"Variance = [double]". This suits the info file from
another integration (see -L).
-W, --graphlinewidth=float
Use a non-default value for the sigmoid line width.
Default is 1.0.
-w, --varconf=integer
Get the confidence limits of the variance using n
by performimg n simultaions.
-y, --varconfpercent=float
Get the higher and lower limits to calculate the limits
of the variance (see -w). Default is 0.05.
-z, --outstats=filename
To use a non-default stats file name.
--emergencysweep Use a sweep method instead of the Levenberg-Marquardt
algorithm if the number of tries (see -m) is reached.
Default number of decimals is 3, for different precision
use --sweepdecimals.
--emergencyvariance In the case the maximum iterations are reached (see -m),
force the seed variance as emergency variance.
--tags=string To define a tag to distinguish groups to perform the
integration. The tag can be used by inclusion, such as
--tags="mod"
or by exclusion, putting first the "!" symbol, such as
--tags="!out"
Tags should be included in a third column of the
relations file. Note that the tag "!out" for outliers is
implicit.
Different tags can be combined using logical operators
"and" (&), "or" (|), and "not" (!), and parentheses.
Some examples:
--tags="!out&mod"
--tags="!out&(dig0|dig1)"
--tags="(!dig0&!dig1)|mod1"
--tags="mod1|mod2|mod3"
--randomseed=float The seed to be used in case the variance calculation
requires a random seed to be calculated (default is 0;
see also -m and --randomtimer).
--randomtimer When this is included, the hash of the current time is
used as seed in the case the variance requires a random
seed to be recalculated (see -m). If omitted, the seed
used is 0. Note --randomtimer overrides --randomseed.
For reproducibility, the hash of the time used is
included in the infoFile, so using --randomseed with
that value should give the exact same results.
--sweepdecimals=float
The number of decimals up to which the variance will be
calculated if the maximum number of tries of the
Levenberg-Marquardt algorithm is reached (option -m),
and the --emergencysweep option is on. Default is 3.
--xlabel=string Use the selected string for the X label. Default is
"Zij". To remove the label, use --xlabel=" ".
--ylabel=string Use the selected string for the Y label. Default is
"Rank/N". To remove the label, use --ylabel=" ".
examples (use "sanxot.py" if you are not using the standalone version):
- To calculate the variance starting with a seed = 0.02, using a datafile.txt
and a relationsfile.txt, both in C:\temp:
sanxot -dC:\temp\datafile.txt -rrelationsfile.txt -v0.02
- To get fast results of an integration forcing a variance = 0.02922:
sanxot -dC:\temp\datafile.txt -rrelationsfile.txt -f -v0.02922
- To get an integration forcing the variance reported in the info file at
C:\data\infofile.txt, and saving the resulting graph in C:\data\ instead
of C:\temp\:
sanxot -dC:\temp\datafile.txt -rrelationsfile.txt -f -VC:\data\infofile.txt -GC:\data\graphFile.png
