====== Automatic Mode ======
===== Introduction =====

This mode has no user interface. 
The automatic mode allow to execute a set of operations, defined in a script file, on a specific Mascot® identification result. The script file is the same as the one used in batch mode. See [[batchuserguide|IRMa batch documentation]]. 

===== Running auotIRMa =====
An exemple is done in the runautoIRMa.bat file under <IRMa_HOME>

To run the autoIRMa on a Mascot® identification result :

  java -Djava.library.path=./lib -Xms256m -Xmx512m -cp IRMa-<version>.jar cea.irma.autoIRMa <resultURL> <mascotDatPath> -s <scriptFile>

Where 
  * <resultFile> is the mascot result file (e.g /20080521/F035548.dat)
  * <mascotDatPath> is the path to directories containing mascot dat files
  * <scriptFile> specify the xml file containing irma instructions. (See [[batchuserguide|IRMa batch documentation]])

===== Integration into Mascot Daemon® =====
The main purpose of this mode is that it permits IRMa integration into existing, automatic, workflows such as Mascot Daemon®. 

==== VBScripts ====

IRMa comes with three Visual Basic scripts (<IRMa_HOME>/VBscripts) to allow to run autoIRMa using wscript so from Mascot Daemon® :

  * autoIRMa.vbs :  Runs autoIRMa on a Mascot® search result. Parameters  ''resultfile'' (specifying with .dat file to validate) and ''script'' (specifying which script file to use) are mandatory.

:!: This VBScript defines a variable indicating the <IRMa_HOME> directory and an other variable indicating where Mascot® .dat files are stored. This latest directory should be accessible from the Mascot Daemon® Service Owner. \\
:!: -Xms argument should NOT be specified in the VBScript !!

  * renameMGF.vbs : Rename MGF generated by the task if it import data from raw files using MascotDistiller®. Parameter ''peakfile'' is mandatory

  * master.vbs : Runs autoIRMa.vbs and renameMGF.vbs. If the task is run using MGF files the renameMGF is not necessary but the script still works. Parameters are those mandatory in both //sub VBScripts//.

==== Integration ====
IRMa can be invoked, as an external process, by the Mascot Daemon® software, which controls raw data pre-processing and Mascot® searches. When defining a new Mascot Daemon® task, you can invoke a script provided in IRMa distribution.

  - Select "External Process in ''Actions'' group
  - Enter the following command in the ''After each search'' section, in order to be able to validate each Mascot® search result.

    wscript "[Path\To\IRMaVBScripts]\master.vbs" /peakfile:"<cachedpeaklist>" 
       /resultfile:"<resultfilename>" 
       /script:"[Path\To\IRMaScripts]\script_TEST_DB.xml"

  * [Path\To\IRMaVBScripts] : to be replaced by the absolute path to directory where VBScript are stored. It is RECOMMENDED to create a directory for each version of IRMa in order to be sure to use appropriated scripts.
  * [Path\To\IRMaScripts] : to be replaced by the absolute path to directory where IRMa instruction scripts are stored.
  * <cachedpeaklist> and <resultfilename> are automatically replaced by, respectively, the full path to generated MGF (if a Data Import Filter has been specified in task) and the Mascot Result file. 
==== Scripts ====

Scripts are written in XML format. XML format  That is, very simply, a set of blocs (nested or successive) with a opening and closing tag... 

<code>
<script> // Opening tag for script bloc
   ... // bloc content
</script> // closing tag for script bloc
</code>
Every script should be described  in a script bloc, as shown above. A script is a set of actions corresponding to IRMa operation to be executed. The execution order of these operations will be identical to the action description order in the script file.

=== Mascot result parse  ===

This opération is only possible on Mascot identification and not on previously saved IRMa project (.irma). This action correspond to the execution of Mascot parse in IRMa using same  parameters as those entered in Report Settings/Parser Properties dialog

//Parse//  bloc is defined as follow :  ''parse'' tag, followed by a  ''parameters'' tag which contains all parameters to be used. Each parameter is described in a ''parameter'' tag and a name and value should be specified.

__Parse bloc example:__
<code xml>
   <parse>
    <parameters>
      <parameter name="is.hit.count.auto">
        <value class="boolean">true</value>
      </parameter>
      <parameter name="protein.cutoff">
        <value class="double">0.05</value>
      </parameter>
      <parameter name="ions.score.cutoff">
        <value class="int">0</value>
      </parameter>
      <parameter name="subset.threshold">
        <value class="double">0.5</value>
      </parameter>
      <parameter name="read.sequence">
        <value class="string">masters</value>
      </parameter>
    </parameters>
  </parse>
</code>

__Available parameters:__
  * name: ''is.hit.count.auto''; allowed values ''false'' or ''true'' ; Specify how to obtain the hits list, with an absolute number of hit (false) or specifying a p value (true)
    * name: ''protein.cutoff''; double value; Specify the p value to use to obtain the hits list. parameter used if ''is.hit.count.auto'' = true
    * name: ''hit.count''; integer value; Specify the number of hit to get. parameter used if ''is.hit.count.auto'' =  false
  * name: ''ions.score.cutoff''; integer value; Specify the peptide score threshold - only peptides with a higher score will be considered-
  * name: ''subset.threshold''; integer value ; Specify the threshold to used in order to import subset proteins. to import a subset protein the following rule should be verified : Subset_Prot_score >= Master_Prot_score * (1-subset.threshold)
  * name: ''read.sequence''; allowed values: ''never'', ''masters'' ou ''always''; Specify the rule to use to read protein sequence (get sequence only if present in identification result file,  get sequence from mascot server for master proteins if necessary, get sequence from mascot server for all proteins)




=== Peptide specific and score filter  ===

<code xml>
  <delete.Proteins>
    <parameters>
      <parameter name="is.freeze.fp.analysis">
        <value class="boolean">true</value>
      </parameter>
      <parameter name="peptides.count">
        <value class="int">1</value>
      </parameter>
      <parameter name="peptides.score">
        <value class="int">20</value>
      </parameter>
      <parameter name="peptides.unicity">
        <value class="boolean">true</value>
      </parameter>
    </parameters>
  </delete.Proteins>
</code>

=== Single match per query filter  ===

**Nota** : no parameter to set.

<code xml>
  <filter.PSM>
    <parameter name="filter.class.name">
      <value class="string">cea.irma.model.validation.SingleMatchPerQueryFilter</value>
    </parameter>
  </filter.PSM>
</code>

=== FPR seeker filter ===

  * FPR = False Positive Rate
  * SaR = Score and Rank
  * DM = Delta Mass
See inside xml below to find comments:
<code xml>
  <filter.FPR.Seeker>
    <parameters>
      <parameter name="seek.fpr.with.score.and.rank.filter">
        <value class="boolean">true</value> <!-- true : the SaR filter will be used. Set to false if you juste want DM to be used. If both are set to false, the default one (SaR) will be used-->
      </parameter>
      <parameter name="seek.fpr.with.delta.mass.filter">
        <value class="boolean">true</value> <!-- true : the DM filter will be used. Set to false if you juste want SaR to be used. If both are set to false, the default one (SaR) will be used-->
      </parameter>
      <parameter name="sought.fpr.in.percentage">
        <value class="double">1.0</value>
      </parameter>
    </parameters>
  </filter.FPR.Seeker>
</code>

=== Master protein filter  ===
:!: If the master protein change is leading to an ambiguous peptide suppression (because the new master protein don't have match with it), the script will suppress it. It's a different behaviour than manual master protein changing in IRMa application, where a dialog ask the user to decide what to do.\\
:!: The "filter.master.rule.operation" parameter can be :
  * CONTAINS_RULE
  * NOT_CONTAINS_RULE
  * BEGINS_WITH_RULE
  * ENDS_WITH_RULE

__Simple Rule example:__
<code xml>
<filter.Master>
    <rules.list>
      <rule name="R1">
        <parameter name="filter.master.rule.operation">
          <value class="rule.operation">ENDS_WITH_RULE</value>
        </parameter>
        <parameter name="filter.master.applies.to.description">
          <value class="boolean">false</value>
        </parameter>
        <parameter name="filter.master.applies.to.accession">
          <value class="boolean">true</value>
        </parameter>
        <parameter name="filter.master.searched.string">
          <value class="string">_HUMAN</value>
        </parameter>
        <parameter name="filter.master.rule.name">
          <value class="string">R1</value>
        </parameter>
      </rule>
    </rules.list>
    <rules.composition value="R1"/>
  </filter.Master>
</code>

__Dual rules example:__

<code xml>
 <filter.Master>
    <rules.list>
      <rule name="R1">
        <parameter name="filter.master.rule.operation">
          <value class="rule.operation">ENDS_WITH_RULE</value>
        </parameter>
        <parameter name="filter.master.applies.to.description">
          <value class="boolean">false</value>
        </parameter>
        <parameter name="filter.master.applies.to.accession">
          <value class="boolean">true</value>
        </parameter>
        <parameter name="filter.master.searched.string">
          <value class="string">_HUMAN</value>
        </parameter>
        <parameter name="filter.master.rule.name">
          <value class="string">R1</value>
        </parameter>
      </rule>
      <rule name="R2">
        <parameter name="filter.master.rule.operation">
          <value class="rule.operation">NOT_CONTAINS_RULE</value>
        </parameter>
        <parameter name="filter.master.applies.to.description">
          <value class="boolean">true</value>
        </parameter>
        <parameter name="filter.master.applies.to.accession">
          <value class="boolean">false</value>
        </parameter>
        <parameter name="filter.master.searched.string">
          <value class="string">tr</value>
        </parameter>
        <parameter name="filter.master.rule.name">
          <value class="string">R2</value>
        </parameter>
      </rule>
    </rules.list>
    <rules.composition value="R1 and R2"/>
  </filter.Master>
 </code>


=== MGF Export ===
  * Parameters
    * Result MGF destination directory
    * The other parameters (what data will be export) are taken from java_option, so this data must be set in IRMa application (Tools => Preferences => Queries export) before using the script
  * The result MGF file will be named as the "sourcefile" information contains in the identification. If this "sourcefile" has been a MGF file no name transformation is done, if not the extension will be change to ".mgf"
  * No possibility, as in IRMa application to choose a corresponding mgf to generate a new one. This script is based only on information contained in the identification

<code xml><export.MGF baseFilePath="Path/to/export/directory" /></code>

=== Database Export ===
  * Parameters
    * for "export.DB", the parameter **"version"** is optional. Its value can be "D" or "E" (default) depending of the version of MSIdb you want to export to. If no parameter is given or if its value is different  from the two accepted the default one will be chosen.
<code xml>
  <export.DB dbVersion="E">
    <config>
      <parameters>
        <parameter name="db.export.user">
          <value class="string">username</value>
        </parameter>
        <parameter name="db.export.pswd">
          <value class="string">passwd</value>
        </parameter>
        <parameter name="db.export.driver">
          <value class="string">org.postgresql.Driver</value>
        </parameter>
        <parameter name="db.export.dbname">
          <value class="string">MSIdb_Name</value>
        </parameter>
        <parameter name="db.export.url">
          <value class="string">jdbc:postgresql://DB_Server_Address:DB_Server_Port/MSIdb_Name</value>
        </parameter>
        <parameter name="db.export.unassigned.peptides">
          <value class="boolean">false</value>
        </parameter>
        <parameter name="db.export.unassigned.queries">
          <value class="boolean">false</value>
        </parameter>
      </parameters>
    </config>
  </export.DB>
</code>