hi -
We have few sets of tutorial scripts that are currently scattered in various modules within imp and outside of imp. I think it would make sense to have a module named tutorials and then subdirectories for the different tutorials. For example, our recent book chapter on assembly modeling by comparative modeling and em can go there.
thoughts?
keren.
How are tutorials different from examples?
On Oct 29, 2010, at 11:15 PM, Keren Lasker wrote:
> > We have few sets of tutorial scripts that are currently scattered in > various modules within imp and outside of imp. > I think it would make sense to have a module named tutorials and then > subdirectories for the different tutorials. For example, our recent > book chapter on assembly modeling by comparative modeling and em can > go there. >
because they are a set of scripts that should be run together. so it more of a protocol then an example of a specific functionality. On Oct 30, 2010, at 12:49 AM, Daniel Russel wrote:
> How are tutorials different from examples? > > On Oct 29, 2010, at 11:15 PM, Keren Lasker wrote: > >> >> We have few sets of tutorial scripts that are currently scattered in >> various modules within imp and outside of imp. >> I think it would make sense to have a module named tutorials and then >> subdirectories for the different tutorials. For example, our recent >> book chapter on assembly modeling by comparative modeling and em can >> go there. >> > > _______________________________________________ > IMP-dev mailing list > IMP-dev@salilab.org > https://salilab.org/mailman/listinfo/imp-dev
we also have applications...
On Sat, Oct 30, 2010 at 10:47 AM, Keren Lasker kerenl@salilab.org wrote: > because they are a set of scripts that should be run together. > so it more of a protocol then an example of a specific functionality. > On Oct 30, 2010, at 12:49 AM, Daniel Russel wrote: > >> How are tutorials different from examples? >> >> On Oct 29, 2010, at 11:15 PM, Keren Lasker wrote: >> >>> >>> We have few sets of tutorial scripts that are currently scattered in >>> various modules within imp and outside of imp. >>> I think it would make sense to have a module named tutorials and then >>> subdirectories for the different tutorials. For example, our recent >>> book chapter on assembly modeling by comparative modeling and em can >>> go there. >>> >> >> _______________________________________________ >> IMP-dev mailing list >> IMP-dev@salilab.org >> https://salilab.org/mailman/listinfo/imp-dev > > _______________________________________________ > IMP-dev mailing list > IMP-dev@salilab.org > https://salilab.org/mailman/listinfo/imp-dev >
i am not completely sure how to best divide application module/bin, module/example. To my understanding applications was suppose to be a complete protocol for a specific complex (such as Nup84). I added simple scripts like resampling / simulating density maps to applications/em, but they should probably move to em/bin. the problems with the current system are: 1. when someone opens IMP and looks for where to start, it would be good to direct to clear and simple tutorials. This is not the case now. 2. each application in application/module and tutorials uses more than one module, so users that want to look for application of modeling +em should go to atom / modeller / em / 2dem / multifit - its not clear.
My suggestion is: module/example - simple examples of specific code as now module/bin - utilities to run functionalities of the module that produce meaningful output (basically what that is in applications now and javi's 2dem/bin is a great example) applications/method - subdirectory for each complete method (paper) + tutorial if written applications/systems - subdirectory for each biological system (such as Nup84)
I do not have strong preferences either way so what ever decided is ok with me, as long as we will decide on a clear definition for what should go where.
On Oct 30, 2010, at 11:13 AM, Dina Schneidman wrote:
> we also have applications... > > On Sat, Oct 30, 2010 at 10:47 AM, Keren Lasker kerenl@salilab.org > wrote: >> because they are a set of scripts that should be run together. >> so it more of a protocol then an example of a specific functionality. >> On Oct 30, 2010, at 12:49 AM, Daniel Russel wrote: >> >>> How are tutorials different from examples? >>> >>> On Oct 29, 2010, at 11:15 PM, Keren Lasker wrote: >>> >>>> >>>> We have few sets of tutorial scripts that are currently scattered >>>> in >>>> various modules within imp and outside of imp. >>>> I think it would make sense to have a module named tutorials and >>>> then >>>> subdirectories for the different tutorials. For example, our recent >>>> book chapter on assembly modeling by comparative modeling and em >>>> can >>>> go there. >>>> >>> >>> _______________________________________________ >>> IMP-dev mailing list >>> IMP-dev@salilab.org >>> https://salilab.org/mailman/listinfo/imp-dev >> >> _______________________________________________ >> IMP-dev mailing list >> IMP-dev@salilab.org >> https://salilab.org/mailman/listinfo/imp-dev >> > _______________________________________________ > IMP-dev mailing list > IMP-dev@salilab.org > https://salilab.org/mailman/listinfo/imp-dev
Order swapped.
On Oct 30, 2010, at 11:36 AM, Keren Lasker wrote: > > My suggestion is: > module/example - simple examples of specific code as now > module/bin - utilities to run functionalities of the module that > produce meaningful output (basically what that is in applications now > and javi's 2dem/bin is a great example) > applications/method - subdirectory for each complete method (paper) + > tutorial if written > applications/systems - subdirectory for each biological system (such > as Nup84 This is the current organization, there is just a shortage of things in all of the categories, especially as one gets further down the list :-) We also don't have a way to specify for an application whether the code is intended to be read or not (so it should be include in the list of examples).
> i am not completely sure how to best divide application module/bin, > module/example. > To my understanding applications was suppose to be a complete protocol > for a specific complex (such as Nup84). > I added simple scripts like resampling / simulating density maps to > applications/em, but they should probably move to em/bin. > the problems with the current system are: > 1. when someone opens IMP and looks for where to start, it would be > good to direct to clear and simple tutorials. This is not the case now. Sure, there should be more tutorials/examples in a easy to find place, but I don't see that an example module vs a tutorial module is a clean divide to have both.
> 2. each application in application/module and tutorials uses more > than one module, so users that want to look for application of modeling > +em should go to atom / modeller / em / 2dem / multifit - its not > clear.
Yeah, it would be nice to automatically generate links from a module to all example code which uses it. I'm not sure how to do things, but I haven't looked. Just scanning the example files from other places for "import IMP.modulename" and "#include <IMP/modulename" and including this list in the example page for the module would be pretty easy to implement.
> > > On Oct 30, 2010, at 11:13 AM, Dina Schneidman wrote: > >> we also have applications... >> >> On Sat, Oct 30, 2010 at 10:47 AM, Keren Lasker kerenl@salilab.org >> wrote: >>> because they are a set of scripts that should be run together. >>> so it more of a protocol then an example of a specific functionality. >>> On Oct 30, 2010, at 12:49 AM, Daniel Russel wrote: >>> >>>> How are tutorials different from examples? >>>> >>>> On Oct 29, 2010, at 11:15 PM, Keren Lasker wrote: >>>> >>>>> >>>>> We have few sets of tutorial scripts that are currently scattered >>>>> in >>>>> various modules within imp and outside of imp. >>>>> I think it would make sense to have a module named tutorials and >>>>> then >>>>> subdirectories for the different tutorials. For example, our recent >>>>> book chapter on assembly modeling by comparative modeling and em >>>>> can >>>>> go there. >>>>> >>>> >>>> _______________________________________________ >>>> IMP-dev mailing list >>>> IMP-dev@salilab.org >>>> https://salilab.org/mailman/listinfo/imp-dev >>> >>> _______________________________________________ >>> IMP-dev mailing list >>> IMP-dev@salilab.org >>> https://salilab.org/mailman/listinfo/imp-dev >>> >> _______________________________________________ >> IMP-dev mailing list >> IMP-dev@salilab.org >> https://salilab.org/mailman/listinfo/imp-dev > > _______________________________________________ > IMP-dev mailing list > IMP-dev@salilab.org > https://salilab.org/mailman/listinfo/imp-dev
Next version of the proposal: - mudulename/bin becomes internal, undocumented, utility executables (eg the benchmarks). They will not get installed in build/bin or installed at all with imp. protein_ligand_score gets moved to
- applications which has executables that users are supposed to see (we will add facility to document the applications in a similar manner to how modules are currently documented). The code is not expected to be read by random users and the applications will get build into build/bin and installed in bin.
- a new directory, biological_systems will be added. In there will be scripts with data that have been published in separate papers about the biological system in question, The scripts should be written so as to be readable and modifiable by others.
Comments?
On Oct 30, 2010, at 11:36 AM, Keren Lasker wrote:
> i am not completely sure how to best divide application module/bin, > module/example. > To my understanding applications was suppose to be a complete protocol > for a specific complex (such as Nup84). > I added simple scripts like resampling / simulating density maps to > applications/em, but they should probably move to em/bin. > the problems with the current system are: > 1. when someone opens IMP and looks for where to start, it would be > good to direct to clear and simple tutorials. This is not the case now. > 2. each application in application/module and tutorials uses more > than one module, so users that want to look for application of modeling > +em should go to atom / modeller / em / 2dem / multifit - its not > clear. > > My suggestion is: > module/example - simple examples of specific code as now > module/bin - utilities to run functionalities of the module that > produce meaningful output (basically what that is in applications now > and javi's 2dem/bin is a great example) > applications/method - subdirectory for each complete method (paper) + > tutorial if written > applications/systems - subdirectory for each biological system (such > as Nup84) > > I do not have strong preferences either way so what ever decided is ok > with me, as long as we will decide on a clear definition for what > should go where. > > > On Oct 30, 2010, at 11:13 AM, Dina Schneidman wrote: > >> we also have applications... >> >> On Sat, Oct 30, 2010 at 10:47 AM, Keren Lasker kerenl@salilab.org >> wrote: >>> because they are a set of scripts that should be run together. >>> so it more of a protocol then an example of a specific functionality. >>> On Oct 30, 2010, at 12:49 AM, Daniel Russel wrote: >>> >>>> How are tutorials different from examples? >>>> >>>> On Oct 29, 2010, at 11:15 PM, Keren Lasker wrote: >>>> >>>>> >>>>> We have few sets of tutorial scripts that are currently scattered >>>>> in >>>>> various modules within imp and outside of imp. >>>>> I think it would make sense to have a module named tutorials and >>>>> then >>>>> subdirectories for the different tutorials. For example, our recent >>>>> book chapter on assembly modeling by comparative modeling and em >>>>> can >>>>> go there. >>>>> >>>> >>>> _______________________________________________ >>>> IMP-dev mailing list >>>> IMP-dev@salilab.org >>>> https://salilab.org/mailman/listinfo/imp-dev >>> >>> _______________________________________________ >>> IMP-dev mailing list >>> IMP-dev@salilab.org >>> https://salilab.org/mailman/listinfo/imp-dev >>> >> _______________________________________________ >> IMP-dev mailing list >> IMP-dev@salilab.org >> https://salilab.org/mailman/listinfo/imp-dev > > _______________________________________________ > IMP-dev mailing list > IMP-dev@salilab.org > https://salilab.org/mailman/listinfo/imp-dev
As an IMP user I cannot help but jump into that conversation.
Maybe it's because I am a mathematician, but I think setting the terminology is an important prior work, and I have the feeling all terms are not well specified yet, though there seem to be a slow convergence towards the following semantics :
- Examples : a very short piece of code solely intended to highlight the very specific aspect it exemplifies (e.g. the sample code on the ConnectivityRestraint html page). If I understand it well, examples are actually found in modules/example subdirectories only in the svn source dir (i.e. not in the installed dir), and automatically included in the manual pages. I think it is OK like that, though it might be useful to let the user install examples as well, maybe in a distinct directory (share/examples/modules/ ?).
- Applications : utility scripts and binaries developed on top of IMP (fox application, multifit scripts, scripts to transform coordinates of atoms in a PDB file) I am not sure I like the term 'application' because it is somehow ambiguous and could be read as 'application of IMP', thus biasing expectations towards 'examples', 'tutorials', 'exercises', or 'biological applications'. As a replacement I would suggest softwares, binaries, utilities, executables… Anyway, this is probably a matter of taste, and any choice is good as long as the definitions are documented (for instance on the first page of the manual). I don't know also if it would not make sense to discriminate between 'utilities' (isolated scripts or binaries that can be used to achieve useful tasks in various situations, such as the transformations of coods for ATOMS in a PDB file) and plain 'software' (more connoted to a dedicated application : fox and multifit binaries), and maybe sort scripts in subdirectories for each distinct softwares so as to make clear for instance what belongs to the multifit protocol etc…
- biological_systems : all scripts and data that where used in a published paper Once again, I am not really keen on the term, but this time because I think it is not descriptive enough. Maybe biological applications would suit better. Also, it would be worth making clear the goals of this directory : providing examples of IMP usage in real life applications ? Providing base scripts that can be modified by users for testings/understanding how IMP works ? Providing a repository to ease re-run and verification of published works ? ...
I would also add tutorials :
- Tutorials : A fully step by step documented script or series of scripts, intended to fully explain the usage of one or several IMP aspects. Writing tutorials is probably time consuming and notw gratifying at all, it is nonetheless critical to help people find their way among the main directions of a tentacular project such as IMP. I'll try and make my first "groping and discovering" scripts into a first tutorial that I'll place in the IMP wiki.
Le 5 nov. 2010 à 22:54, Daniel Russel a écrit :
> Next version of the proposal: > - mudulename/bin becomes internal, undocumented, utility executables (eg the benchmarks). They will not get installed in build/bin or installed at all with imp. protein_ligand_score gets moved to > > - applications which has executables that users are supposed to see (we will add facility to document the applications in a similar manner to how modules are currently documented). The code is not expected to be read by random users and the applications will get build into build/bin and installed in bin. > > - a new directory, biological_systems will be added. In there will be scripts with data that have been published in separate papers about the biological system in question, The scripts should be written so as to be readable and modifiable by others. > > Comments?
Overall, I think everyone is in broad agreement.
On the example/tutorial distinction: I don't see that there is a clear difference between "a very short piece of code solely intended to highlight the very specific aspect " and "A fully step by step documented script or series of scripts, intended to fully explain the usage of one or several IMP aspects". I would expect that any example provides a full step-by-step explanation of what it is trying to show (and is definitely trying to show one or more of IMPs aspects).
In my experience, software tutorials (in contrast to examples) generally refer to something that is primarily text or a video or a lecture (presumably including lots of bits of code). As such, a well documented piece of source or set of sources and data doesn't really fit the definition (but Keren and Ben's tutorial does). In contrast an example is a piece of code which some text inserted in it. Under this split, each tutorial would have accompanying example code, which could go with other example code (since it works fine as "just" example code in addition to be referred to in the tutorial).
Open questions: - where to put multi-module example code: I've been saying it should just go into a module or the kernel. We can always add a list of examples referencing a given module, and I'll bet we can do that on a class/function level given a little time. Actually that would be pretty awesome: have a automatically generated list, for each class/function, what examples use it.
- what to do with tutorial text and videos as well as other IMP-related publications. Perhaps have a publications directory?
- I really don't really like the "applications" name either, but do like it better than the alternatives we have so far. Keren and I had discussed having a subdir of applications called "utilities" which were just random little useful scripts. I'm not sure these names really matter as long as they are documented (which they currently are not).
Minor comments: - examples are currently installed with the documentation - I don't really like have example code that is just a snippet of code since then there is no way to have the code run automatically. And, in my experience, when code is not run, bit rot tends to set in.
> - Examples : a very short piece of code solely intended to highlight the very specific aspect it exemplifies (e.g. the sample code on the ConnectivityRestraint html page). > If I understand it well, examples are actually found in modules/example subdirectories only in the svn source dir (i.e. not in the installed dir), and automatically included in the manual pages. I think it is OK like that, though it might be useful to let the user install examples as well, maybe in a distinct directory (share/examples/modules/ ?).
> > - Applications : utility scripts and binaries developed on top of IMP (fox application, multifit scripts, scripts to transform coordinates of atoms in a PDB file) > I am not sure I like the term 'application' because it is somehow ambiguous and could be read as 'application of IMP', thus biasing expectations towards 'examples', 'tutorials', 'exercises', or 'biological applications'. As a replacement I would suggest softwares, binaries, utilities, executables… Anyway, this is probably a matter of taste, and any choice is good as long as the definitions are documented (for instance on the first page of the manual). > I don't know also if it would not make sense to discriminate between 'utilities' (isolated scripts or binaries that can be used to achieve useful tasks in various situations, such as the transformations of coods for ATOMS in a PDB file) and plain 'software' (more connoted to a dedicated application : fox and multifit binaries), and maybe sort scripts in subdirectories for each distinct softwares so as to make clear for instance what belongs to the multifit protocol etc… > > - biological_systems : all scripts and data that where used in a published paper > Once again, I am not really keen on the term, but this time because I think it is not descriptive enough. Maybe biological applications would suit better. Also, it would be worth making clear the goals of this directory : providing examples of IMP usage in real life applications ? Providing base scripts that can be modified by users for testings/understanding how IMP works ? Providing a repository to ease re-run and verification of published works ? ... > > I would also add tutorials : > > - Tutorials : A fully step by step documented script or series of scripts, intended to fully explain the usage of one or several IMP aspects. Writing tutorials is probably time consuming and notw gratifying at all, it is nonetheless critical to help people find their way among the main directions of a tentacular project such as IMP. I'll try and make my first "groping and discovering" scripts into a first tutorial that I'll place in the IMP wiki. > > Le 5 nov. 2010 à 22:54, Daniel Russel a écrit : > >> Next version of the proposal: >> - mudulename/bin becomes internal, undocumented, utility executables (eg the benchmarks). They will not get installed in build/bin or installed at all with imp. protein_ligand_score gets moved to >> >> - applications which has executables that users are supposed to see (we will add facility to document the applications in a similar manner to how modules are currently documented). The code is not expected to be read by random users and the applications will get build into build/bin and installed in bin. >> >> - a new directory, biological_systems will be added. In there will be scripts with data that have been published in separate papers about the biological system in question, The scripts should be written so as to be readable and modifiable by others. >> >> Comments? > > > _______________________________________________ > IMP-dev mailing list > IMP-dev@salilab.org > https://salilab.org/mailman/listinfo/imp-dev
On Oct 30, 2010, at 10:47 AM, Keren Lasker wrote:
> because they are a set of scripts that should be run together. > so it more of a protocol then an example of a specific functionality. There is no reason an example can't have more than one script. Restrainer has examples with more than one file, I recall.
> On Oct 30, 2010, at 12:49 AM, Daniel Russel wrote: > >> How are tutorials different from examples? >> >> On Oct 29, 2010, at 11:15 PM, Keren Lasker wrote: >> >>> >>> We have few sets of tutorial scripts that are currently scattered in >>> various modules within imp and outside of imp. >>> I think it would make sense to have a module named tutorials and then >>> subdirectories for the different tutorials. For example, our recent >>> book chapter on assembly modeling by comparative modeling and em can >>> go there. >>> >> >> _______________________________________________ >> IMP-dev mailing list >> IMP-dev@salilab.org >> https://salilab.org/mailman/listinfo/imp-dev > > _______________________________________________ > IMP-dev mailing list > IMP-dev@salilab.org > https://salilab.org/mailman/listinfo/imp-dev
participants (4)
-
Benjamin SCHWARZ -
Daniel Russel -
Dina Schneidman -
Keren Lasker