Feedback on API documentation

[saphia]

Here are several interrogations/suggestions I had while reading the API description:

Main page:

• description of cocoatree.io.export_fasta => "fasta" should be uppercased.
• explain somewhere the abbreviations? MSA, SCA?
• add the references to the example datasets

classes description:

http://tree-bioinfo-intra.timc.fr/projects/cocoa/modules/classes.html

• cocoatree.msa.filter_sequences:
  http://tree-bioinfo-intra.timc.fr/projects/cocoa/modules/generated/cocoatree.msa.filter_sequences.html#cocoatree.msa.filter_sequences
  => La description n'est pas claire : "Filter (1) overly gapped positions; (2) overly gapped sequences.".
  Quel est le type du retour une liste d'identifiants de sequences ou une liste de sequences ?
  Pourquoi c'est un array qui est renvoyé ? Il contient quoi ?

• cocoatree.msa.filter_ref_seq
  Je trouve cette description peu claire : "Remove sequences r with Sr < delta, where Sr is the fractional identity between r and a specified reference sequence."
  Que veut dire "r" ici ? C'est appliqué à toutes les séquences données en entrée n'est-ce pas ?
  Quel comportement quand le "refseq_id" n'est pas donné ? Il est dit qu'il est "computed", mais comment le choix est-il fait ?

• cocoatree.msa.map_to_pdb

  • Un détail : cette fonction est décrite comme "Mapping of the unfiltered MSA positions on a PDB structure."
    Selon les paramètres passés, j'aurais dit que cela pourrait fonctionner également sur les MSA filtrés ? (même si l'intérêt est sans doute limité ?).
    Est-ce que la sequence du PDB "pdb_seq" n'est pas deja de base dans "sequences"? Est-ce que ça ne suffirait pas d'avoir le paramètre ref_seq_id?
    (peut-être à renommer pour cohérence "pdb_seq_id"? cf aussi plus bas)

  • Autre chose : "ref_seq_id: str,
    identifier of the sequence the positions are mapped onto. Should be included in seq_list."
    => que représente "seq_list" ici ? est-ce que cela fait référence à l'argument "sequences_id"?
    Est-ce qu'on ne pourrait pas appeler "ref_seq_id" "pdb_seq_id" pour garder la convention de nommage des autres parametres ?

• cocoatree.msa.map_msa_positions
  Je ne comprends pas tout à fait ce que cela fait vus les paramètres...
  "n_loaded_posint,
  Number of positions in the original unfiltered MSA"
  => nom du paramètre et sa description : je trouve que ce n'est pas très clair, c'est bien le "number of positions" (ça semble indiquer une longueur, un nombre de positions), mais ce devrait pas être une liste des indices des positions ?
  Pour le coup la description du 2nd paramètre "remaining_pos" est plus claire. Mais je ne comprends pas que le type ne soit pas le même que l'autre paramètre ?

[margauxjullien]

Main page:

add the references to the example datasets

--> they are included in each dataset documentation, is it necessary to also mention them in the main page?

cocoatree.msa.map_to_pdb

Un détail : cette fonction est décrite comme "Mapping of the unfiltered MSA positions on a PDB structure."
Selon les paramètres passés, j'aurais dit que cela pourrait fonctionner également sur les MSA filtrés ? (même si l'intérêt est sans doute limité ?).

oui ça devrait aussi fonctionner avec la séquence filtrée

Est-ce que la sequence du PDB "pdb_seq" n'est pas deja de base dans "sequences"? Est-ce que ça ne suffirait pas d'avoir le paramètre ref_seq_id?
(peut-être à renommer pour cohérence "pdb_seq_id"? cf aussi plus bas)

la séquence du PDB est censée être dans le MSA, mais souvent les identifiants de séquences dans les alignements sont assez longs, alors que par exemple l'identifiant de la trypsine du rat est juste 3TGI dans le fichier PDB. Effectivement, c'est plus logique de renommer en pdb_seq_id

Autre chose : "ref_seq_id: str,
identifier of the sequence the positions are mapped onto. Should be included in seq_list."
=> que représente "seq_list" ici ? est-ce que cela fait référence à l'argument "sequences_id"?
Est-ce qu'on ne pourrait pas appeler "ref_seq_id" "pdb_seq_id" pour garder la convention de nommage des autres parametres ?

Bien vu, c'est un reliquat d'une ancienne version, j'ai fait les corrections

cocoatree.msa.map_msa_positions
Je ne comprends pas tout à fait ce que cela fait vus les paramètres...
"n_loaded_pos : int,
Number of positions in the original unfiltered MSA"
=> nom du paramètre et sa description : je trouve que ce n'est pas très clair, c'est bien le "number of positions" (ça semble indiquer une longueur, un nombre de positions), mais ce devrait pas être une liste des indices des positions ?
Pour le coup la description du 2nd paramètre "remaining_pos" est plus claire. Mais je ne comprends pas que le type ne soit pas le même que l'autre paramètre ?

on n'a pas besoin de la liste des indices des positions du MSA non filtré car les indices vont forcément de 0 à n_loaded_pos - 1. Ensuite on crée une liste de longueur n_loaded_pos où chaque élément vaut None s'il correspond à une position filtrée, ou l'indice de position dans le MSA filtré si c'est une position qui a été conservée. Et à partir de là, on crée nos dictionnaires de mapping entre les deux versions de l'alignement.
Après c'est peut-être effectivement plus clair pour l'utilisateur si on lui demande en entrée deux paramètres du même type, il nous suffit de mesurer la longueur de la liste au sein de la fonction au lieu de la demander en entrée. @NelleV @ijunier qu'est-ce que vous en pensez ?