2012-04-11 rev 2012-06-09

construire les man à la main (sans roxygen) en vu de générer le package MTK

 

1. Conventions pour les fonctions .Rd

• un fichier "tata-class.Rd" par classe "tat", avec "alias(tata-class)", dans lequel on décrit en particulier:
  
  • la structure de la classe
  • les méthodes d'instance en ajoutant par exemple "alias(name,tata-method)" pour la méthode "name" et en créant un lien vers le fichier "name-methods.Rd". Deux cas:
    • si la description de la méthode instanciée est très simple et très courte, on ne fait rien de plus
    • si elle nécessite plus de 2-3 lignes, on garde une description très rapide ici et on fait un lien vers le fichier "name,tata-method.Rd", où l'on détaille les choses et on déplace l'alias "alias(name,tata-method)"
• un fichier par fonction générique, exemple "name-methods.Rd", en mettant "alias(name)" et "alias(name-methods)". Les méthodes d'instance ne sont pas décrites ici (cf. ci-dessus).
• pour les méthodes d'analyse, d'échantillonnage, de simulation, on crée des fichiers .Rd à part qui décrivent l'ensemble de la méthode et de son utilisation. C'est nécessaire car les fonctions et les classes détaillées ne seront pas visibles de l'utilisateur.
• on récapitule les méthodes d'analyse, etc. dans le fichier "mtk-package.Rd"

 

 

2. Génération du package MTK en vu de construire les man à la main (sans roxygen)

 

procédure 

1. svn checkout svn://scm.mulcyber.toulouse.inra.fr/svnroot/baomexico/trunk/mtk

2. cd mtk/R

3. Sous R :

   1. library(methods); library(stringr); library(XML); library(sensitivity)

   2. listAllFiles <- c('mtkAllGenerics.R', 'mtkProcess.R', 'mtkExpWorkflow.R', 'mtkAnalysor.R', 'mtkResult.R', 'mtkAnalysorResult.R', 'mtkCommonFunctions.R', 'mtkDefaultAnalysor.R', 'mtkValue.R', 'mtkDomain.R', 'mtkExperiment.R', 'mtkExpFactors.R', 'mtkFactor.R', 'mtkFastAnalysor.R','mtkSampler.R', 'mtkFastSampler.R', 'mtkFeature.R' ,'mtkLevel.R', 'mtkModelExamples.R','mtkSimulator.R', 'mtkMorrisAnalysor.R', 'mtkMorrisSampler.R', 'mtkNativeAnalysor.R', 'mtkNativeSampler.R', 'mtkNativeSimulator.R', 'mtkPackage.R', 'mtkParameter.R', 'mtkParsor.R', 'mtkSamplerResult.R', 'mtkIshigamiSimulator.R','mtkSimulatorResult.R', 'mtkWWDMSimulator.R', 'mtkModelExamplesClimat.R', 'globalsMtkFuncts.R', 'plmm-mtk.R', 'mtkPLMMAnalysor.R', 'mtkBasicMonteCarloSampler.R', 'mtkHMMorrisAnalysor.R', 'mtkHMMorrisSampler.R', 'mtkHMSobolAnalysor.R', 'mtkHMSobolSampler.R', 'mtkHMWWDMSimulator.R', 'mtkRegressionAnalysor.R')

   3. package.skeleton("mtk",code_files=listAllFiles, force=TRUE, namespace=TRUE)

   4. fichier NAMESPACE à vérifier

4. pointer les fichiers rd du répertoire man et faire le tri selon le doc de Genolini « construire un package classic et S4 »

   1. TRIER : dans un premier temps j'isole les man des classes et méthodes du groupe « facteur » (celles que j'ai écrites)

   2. Pour chaque fichier je complète le fichier .rd

 

Objectifs des règles de recherches de l'aide sous R (fichiers .rd)

 

Écrire les fichiers d'aide des fonctions, méthodes et classes : ce sont eux qui sont documentés, ils contiennent un alias vers la documentation de la méthode générique (donc le rd correspondant de cette méthode est supprimé)

• help(aclass-class) ou ?aclass-class

  • => doit pointer vers la documentation de la classe aclass

• ?amethod ou ?amethod-methods

  • => doit pointer vers la documentation des méthodes amethod toutes signatures confondues

• ?afunction

  • => doit pointer vers la documentation de fonction afunction

•  

• les fichiers DEBUG.xxx sont supprimés

3. Liste des 229 squelettes Rd générés à la commande package.skeleton

En bleu les man sous le répertoire __HR, en vert sous le répertoire MIAJ

il faut :

• valider la liste de ces fichiers,

• supprimer ceux qui sont identifiés comme redondants et ajouter l'alias dans le fichier correspondant

• remplir l'aide du fichier à la main

• vérifier que l'ensemble fonctionne

addProcess-methods.Rd : --

addProcess.Rd : --

analysor.morris.Rd : --

analysor.sobol.Rd : --

basicMonteCarlo.Rd : --

DEBUG.mtkAnalysor.Rd : à supprimer 

DEBUG.mtkExperiment.Rd : à supprimer 

DEBUG.mtkExpWorkflow.Rd : à supprimer 

DEBUG.mtkNativeAnalysor.Rd : à supprimer 

DEBUG.mtkNativeSampler.Rd : à supprimer 

DEBUG.mtkNativeSimulator.Rd : à supprimer 

DEBUG.mtkParsor.Rd : à supprimer 

DEBUG.mtkProcess.Rd : à supprimer 

DEBUG.mtkSampler.Rd : à supprimer 

DEBUG.mtkSimulator.Rd : à supprimer 

deleteProcess-methods.Rd : --

deleteProcess.Rd : --

fungus.factors.Rd : --

fungus.model.Rd : --

fungus.simule.Rd : --

getDistributionName-methods.Rd : OK

getDistributionName.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

getDistributionNames-methods.Rd : OK

getDistributionNames.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

getDistributionParameters-methods.Rd : OK

getDistributionParameters.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

getDomainFactor-methods.Rd : OK

getDomainFactor.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

getFeatureList-methods.Rd : OK

getFeatureList.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

getLevelList-methods.Rd : OK

getLevelList.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

getName-methods.Rd : OK

getName.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

getNames-methods.Rd : OK

getNames.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

getNominalValueType-methods.Rd : OK

getNominalValueType.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

getParameters-methods.Rd : OK

getValue-methods.Rd : OK

getValue.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

getValueType-methods.Rd : OK

getValueType.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

initialize-methods.Rd : OK

is.finished-methods.Rd :

is.finished.Rd :

ishigami.factors.Rd :

ishigami.model.Rd :

ishigami.simule.Rd :

is.mtkDomain-methods.Rd : OK

is.mtkDomain.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

is.mtkExpFactors-methods.Rd : OK

is.mtkExpFactors.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

is.mtkFactor-methods.Rd : OK

is.mtkFactor.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

is.mtkFeature-methods.Rd : OK

is.mtkFeature.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

is.mtkLevel-methods.Rd :

is.mtkLevel.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

is.mtkParameter-methods.Rd :

is.mtkParameter.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

is.ready-methods.Rd : --

is.ready.Rd : --

lhs003.Rd : --

make.mtkFactor.Rd :

make.mtkFeatureList.Rd :

make.mtkLevelList.Rd :

make.mtkParameterList.Rd :

make.mtkValueList.Rd :

matchType-methods.Rd :

matchType.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

mtkAnalysor-class.Rd : --

mtkAnalysor.Rd : --

mtkAnalysorResult-class.Rd : --

mtkAnalysorResult.Rd : --

mtkBasicMonteCarloSampler-class.Rd : --

mtkBasicMonteCarloSampler.Rd : --

mtkBasicMonteCarloSamplerResult-class.Rd : --

mtkBasicMonteCarloSamplerResult.Rd : --

mtkCopyright.Rd :

mtkDefaultAnalysor-class.Rd : --

mtkDefaultAnalysor.Rd : --

mtkDomain-class.Rd :

mtkDomain.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

mtkExperiment-class.Rd :

mtkExperiment.Rd :

mtkExpFactors-class.Rd :

mtkExpFactors.DEBUG.Rd :

mtkExpFactors.Rd :

mtkExpWorkflow-class.Rd : --

mtkExpWorkflow.Rd : --

mtkFactor-class.Rd :

mtkFactor.Rd :

mtkFastAnalysor-class.Rd : --

mtkFastAnalysor.Rd : --

mtkFastSampler-class.Rd : --

mtkFastSampler.Rd : --

mtkFeature-class.Rd :

mtkFeature.Rd :

mtkHMMorrisAnalysor-class.Rd : --

mtkHMMorrisAnalysor.Rd : --

mtkHMMorrisAnalysorResult-class.Rd : --

mtkHMMorrisAnalysorResult.Rd : --

mtkHMMorrisSampler-class.Rd : --

mtkHMMorrisSampler.Rd : --

mtkHMMorrisSamplerResult-class.Rd : --

mtkHMMorrisSamplerResult.Rd : --

mtkHMSobolAnalysor-class.Rd : --

mtkHMSobolAnalysor.Rd : --

mtkHMSobolAnalysorResult-class.Rd : --

mtkHMSobolAnalysorResult.Rd : --

mtkHMSobolSampler-class.Rd : --

mtkHMSobolSampler.Rd : --

mtkHMSobolSamplerResult-class.Rd : --

mtkHMSobolSamplerResult.Rd : --

mtkHMWWDMSimulator-class.Rd : --

mtkHMWWDMSimulator.Rd : --

mtkHMWWDMSimulatorResult-class.Rd : --

mtkHMWWDMSimulatorResult.Rd : --

mtkIshigamiSimulator-class.Rd : --

mtkIshigamiSimulator.Rd : --

mtkLevel-class.Rd :

mtkLevel.Rd :

mtkMorrisAnalysor-class.Rd : --

mtkMorrisAnalysor.Rd : --

mtkMorrisSampler-class.Rd : --

mtkMorrisSampler.Rd : --

mtkNativeAnalysor-class.Rd : --

mtkNativeAnalysor.Rd : --

mtkNativeSampler-class.Rd : --

mtkNativeSampler.Rd : --

mtkNativeSimulator-class.Rd : --

mtkNativeSimulator.Rd : --

mtk-package.Rd :

mtkParameter-class.Rd :

mtkParameter.Rd :

mtkParsor-class.Rd : --

mtkParsor.Rd : --

mtkPLMMAnalysor-class.Rd : --

mtkPLMMAnalysor.Rd : --

mtkProcess-class.Rd : --

mtkProcess.Rd : --

mtkReadFactors-methods.Rd :

mtkReadFactors.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

mtkRegressionAnalysor-class.Rd : --

mtkRegressionAnalysor.Rd : --

mtkRegressionAnalysorResult-class.Rd : --

mtkRegressionAnalysorResult.Rd : --

mtkResult-class.Rd : --

mtkResult.Rd : --

mtkSampler-class.Rd : --

mtkSampler.Rd : --

mtkSamplerResult-class.Rd : --

mtkSamplerResult.Rd : --

mtkSimulator-class.Rd : --

mtkSimulator.Rd : --

mtkSimulatorResult-class.Rd : --

mtkSimulatorResult.Rd : --

mtkValue-class.Rd :

mtkValue.Rd :

mtkWWDMSimulator-class.Rd : --

mtkWWDMSimulator.Rd : --

names-methods.Rd :

plmm.model.Rd : --

plmm.mtk.Rd : --

plot-methods.Rd : --

plot.mtkmorris.Rd : --

plot.plmm.Rd : --

plot.regressionSI.Rd : --

plot.sobolAnalys.Rd : --

print-methods.Rd : à vérifier (à priori c'est une fonction)

print.mtkLevelList.Rd :

print.mtkLevel.Rd :

print.mtkValueList.Rd :

print.mtkValue.Rd :

print.regressionSI.Rd :

Quantiles.Rd : --

reevaluate-methods.Rd : --

reevaluate.Rd : --

regressionSI.Rd : --

report-methods.Rd : --

report.Rd : --

run-methods.Rd : --

run.Rd : --

sampler.morris.Rd : --

sampler.sobol.Rd : --

serialize-methods.Rd : --

serialize.Rd : --

setDistributionParameters-methods.Rd :

setDistributionParameters.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

setFeatureList-methods.Rd :

setFeatureList.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

setLevelList-methods.Rd :

setLevelList.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

set.mtkExpFactors-methods.Rd :

set.mtkExpFactors.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

setName-methods.Rd :

setName.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

setParameters-methods.Rd :

setParameters.Rd : fichier à supprimer, mettre l'alias dans l'équivalent-methode

setProcess-methods.Rd : --

setProcess.Rd : --

setReady-methods.Rd : --

setReady.Rd : --

setState-methods.Rd : --

setState.Rd : --

setXMLFilePath-methods.Rd : --

setXMLFilePath.Rd : --

show-methods.Rd : --

summary-methods.Rd : --

summary.mtkmorris.Rd : --

summary.plmm.Rd : --

summary.sobolAnalys.Rd : --

weed.decision.Rd : --

weed.factors.Rd : --

weed.fun.Rd : --

weed.model.Rd : --

weed.simule.Rd : --

wwdm.climates.Rd : --

wwdm.factors.Rd : --

wwdm.model.Rd : --

wwdm.simule.Rd : --

xsOff.Rd : --

z[_--methods.Rd :

z[-methods.Rd :

z[[-methods.Rd :

z$_--methods.Rd :

z$-methods.Rd :

1. Création du répertoire trunck/mtk/testsDev/unitTest/

Le fonctionnement de RUnit est différent selon qu'on execute les tests sur un package en mémoire ou sur des fichiers chargés interactivement durant leur développement (actuellement seul le second cas est testé).

 

2. Principe

L'idée de base est la suivante : il s'agit d’exécuter un ensemble de fonctions de tests (nommées selon une convention) et de centraliser le résultat de ces tests dans un document formaté. On a de cette manière une vue synthétique de l'ensemble des résultats des tests.

Pour ce faire il faut respecter 4 étapes :

• créer un objet R « test suite » qui est une collection de fonctions tests et de fichiers relatifs à un sujet (comme une classe par exemple). Cet objet fixe également un certain nombre d'info nécessaires à l’exécution (par exemple la méthode de tirage aléatoire au cas où).

• créer un ou des fichier(s) script R qui contient/contiennent les fonctions exécutant les différents tests.

• exécuter la « test suite » : cet objet va lancer les scripts de fonctions tests

• imprimer le résultat de la série de test dans un doc mis en forme (éventuellement en HTML)

 

3. Choix d'organisation

• On considère comme répertoire racine le rep <root> qui pointe sur

~/<path>/baomexico/trunck/mtk/R

• Les tests unitaires sont dans le répertoire

  <root>/testDev/unitTests

• chaque classe mtk a un répertoire correspondant de test nommé test<mtkClass> (ex : testmtkFactor)

• chaque répertoire de test de classe contient un script R (ex : runmtkFactor.R)

• chacun de ces scripts contient l'ensemble des tests unitaires de méthodes et fonctions propres à la classe

• le résultat de tous les tests est dans le fichier <root>/unitTests/logTests/logUnitTestsMTK.html

 

4. contenu du script R de test unitaire

• .setUp() et .tearDown() sont des fonctions appelées respectivement avant et après l’exécutionUniTests_lisezMoi.odt des tests pour préparer / restaurer l'environnement nécessaire aux tests. Le but étant de veiller à ce qu'aucune variable ou objet de l'environnement R d’exécution provoque un effet de bord.

4. Mode opératoire

• étape 1 : Créer l'objet test suite :

  • Un objet test suite est une liste contenant :

    • un nom

    • un tableau des rep contenant les tests

    • un expression régulière pour identifier les fichiers tests

    • un expression régulière pour identifier les fonctions tests contenues dans ces fichiers

    • les méthodes utilisées pour le tirage aléatoire

  • Nous faisons le choix de créer :(choix à confirmer après usage)

    • une test suite par classe nommé runitmtk<nom_de_la_classe> ex : runitmtkLevel, chaque suite de test correspond à un sous-reprtoire spécifique

    • pour chaque test suite, un fichier composé des fonctions de test des méthodes de la classe

testsuite.mtkLevel <-defineTestSuite(name="mtkLevel", dirs="./testmtkLevel/")

• les test unitaires sont écrits dans le rep ../testDev/test<nom-de-la-classe>

• étape 2 : écrire les fonctions test unitaire

• étape 3 : run des tests :

  • l’exécution se fait en exécutant le script runTEstsScript.R

  • le rapport se trouve dans le répertoire ../mtk/testDev/unitTests/logTests (le nouveau rapport écrase le précédant)

• étape 4 : visualisation des résultats

  • ../mtk/testDev/unitTests/logTests/logUnitTestsMTK.html

 

Ref :

• [1] Ch. Ginolini : construire un package classic et S4 parag 2.2.2

• [2] RUnit König et al, - A Unit test Framework for R sept 2010

 

HR 2011-086-22, Modif du 2012-03-15,  2012-07-09