search

naturalis / supersmart

Self-Updating Platform for the Estimation of Rates of Speciation, Migration And Relationships of Taxa
MIT License
17 stars 5 forks source link

Manual with worked example and troubleshooting #62

Closed diogoprov closed 9 years ago

diogoprov commented 9 years ago

Hi All, I have used the program now for sometime and I must confess that I have struggled a bit on changing the arguments to use the other options of some functions, besides the default. So I think a worked example with step-by-step command list and saying how to change some of the options and what they mean would be nice, so the user don't have to type e.g., smrt help FUNCTION everytime before using a given function. Also, in the website, it's not explicit that the list of commands should be run that specific sequence. I'd also suggest is saying more explicitely which fields/columns should contain in the fossil txt file and which ones are optional. The manual could also contain a short list on how to solve the most common problems or at least how and where to find help for solving them.

Thanks all for your support

rvosa commented 9 years ago

Ok, could you make a list of the problems you've encountered and how you solved them?

diogoprov commented 9 years ago

So here goes some of the things I have encountered:

  1. Before starting the pipeline, copy the files you'll need (e.g., species list or fossil table) into the virtual machine folder cp /vagrant/list_species.txt ~
  2. If you get this kind of error when searching for the species names

ERROR: http://taxosaurus.org/submit?query=Acanthocereus_pentagonus%20 - 500 Can't connect to taxosaurus.org:80 (timeout) WARN: couldn't resolve name Acanthocereus_pentagonus

It's a connection problem and you should just try again.

Maybe Thaís could also add some issues. I'll keep posting the error and how to solve them here as I encounter them .

hettling commented 9 years ago

I am currently working on a more detailed manual in the form of a step-by-step walk-through (commit c0cf35351c8083a26acfc163de8468d43f56ee64). This document is aimed to be very basic such that users which have no experience with command-line interfaces. So far the installation of the virtual machine is covered. We could then include Rutger's documented workflow for the pepper plants as an example of how to run the pipeline.

Ideally the document should be compiled dynamically, i.e. all code contained in the document gets executed when the document is compiled, and the output is reported. This way, it is ensures that the examples work with the current supersmart version.

So far, I used knitr for this, which works on bash commands and can produce markdown, html or latex. Disadvantage is that this requires an r engine and the knitr package (in case we want to compile it on the VM). @rvosa : Do you know of any other dynamic report generators that could work with bash commands?

diogoprov commented 9 years ago

Yes, the manual looks fine, but I also asked myself how would it be with languages other than R. I know that the RStudio editor supports other languages in building a markdown document, but I haven't a clue on if it would call the program in the virtual machine... so far I have just used markdown with R scripts

rvosa commented 9 years ago

We've switched to using the wiki: https://github.com/naturalis/supersmart/wiki

rvosa commented 9 years ago

@diogoprov, When you say: "Before starting the pipeline, copy the files you'll need (e.g., species list or fossil table) into the virtual machine folder cp /vagrant/list_species.txt ~" - what do you mean exactly? As far as I know there is no need to copy files from the synchronized folder /vagrant to anywhere else inside the VM. In fact, I would generally advise against that. Did you need to do this? What problem were you trying to solve?

diogoprov commented 9 years ago

The wiki looks better indeed. I think it would be even easier to keep updated.

diogoprov commented 9 years ago

I needed to do it because otherwise functions like smrt taxize didn't recognize the species list files, even when they were already in the shared folder... I don't know ahy this happens, but this was the only way I managed to got it working...

rvosa commented 9 years ago

Are you still having this issue? What do you mean by "didn't recognize the species list"? If you go into /vagrant and have a file "names.txt" in there, then run smrt taxize -i names.txt, what message do you get?

diogoprov commented 9 years ago

I didn't have this issue after I copied, but before when I tried to to sth like smrt taxize -i species_list.txt I got an error saying that the file doesn't exist. It also didnt appear when I did $ls.

rvosa commented 9 years ago

Did this take place inside the /vagrant folder?

On Thu, May 21, 2015 at 10:18 PM, Diogo B. Provete <notifications@github.com

wrote:

I didn't have this issue after I copied, but before when I tried to to sth like smrt taxize -i species_list.txt I got an error saying that the file doesn't exist. It also didnt appear when I did $ls.

— Reply to this email directly or view it on GitHub https://github.com/naturalis/supersmart/issues/62#issuecomment-104408726 .

diogoprov commented 9 years ago

Exactly. @hettling suggested to me and Boni to copy the files to the /vagrant/ machine, like this cp /vagrant/list_species.txt ~ and then it worked fine

rvosa commented 9 years ago

Mmmm... that's unfortunate. I've never seen that. But this problem went away, or are you still having to do that?

On Fri, May 22, 2015 at 9:59 AM, Diogo B. Provete notifications@github.com wrote:

Exactly. @hettling https://github.com/hettling suggested to me and Boni to copy the files to the /vagrant/ machine, like this cp /vagrant/list_species.txt ~ and then it worked fine

— Reply to this email directly or view it on GitHub https://github.com/naturalis/supersmart/issues/62#issuecomment-104556970 .

diogoprov commented 9 years ago

well, right now my 'vagrant up' stop working and I'm doing a fresh install again. I hope it work after I allocate more memory to it. But it happened the same with the older version 0.1, I couldn't get it to work without copying the file first

rvosa commented 9 years ago

How are you starting and stopping the virtual machine? I think it might be the case that vagrant is less happy when you power off and on in VirtualBox than when you do this with 'vagrant halt' and 'vagrant up'.

On Fri, May 22, 2015 at 2:42 PM, Diogo B. Provete notifications@github.com wrote:

well, right now my 'vagrant up' stop working and I'm doing a fresh install again. I hope it work after I allocate more memory to it. But it happened the same with the older version 0.1, I couldn't get it to work without copying the file first

— Reply to this email directly or view it on GitHub https://github.com/naturalis/supersmart/issues/62#issuecomment-104650155 .

diogoprov commented 9 years ago

Yes, I always try to do vagrant halt, but then I got an error:

macbooksprovete:supersmart diogoborgesprovete$ vagrant halt

An action 'halt' was attempted on the machine 'default',

but another process is already executing an action on the machine.

Vagrant locks each machine for access by only one process at a time.

Please wait until the other Vagrant process finishes modifying this

machine, then try again.

If you believe this message is in error, please check the process

listing for any "ruby" or "vagrant" processes and kill them. Then

try again.

2015-05-22 14:58 GMT+02:00 Rutger Vos notifications@github.com:

How are you starting and stopping the virtual machine? I think it might be the case that vagrant is less happy when you power off and on in VirtualBox than when you do this with 'vagrant halt' and 'vagrant up'.

On Fri, May 22, 2015 at 2:42 PM, Diogo B. Provete < notifications@github.com> wrote:

well, right now my 'vagrant up' stop working and I'm doing a fresh install again. I hope it work after I allocate more memory to it. But it happened the same with the older version 0.1, I couldn't get it to work without copying the file first

— Reply to this email directly or view it on GitHub < https://github.com/naturalis/supersmart/issues/62#issuecomment-104650155> .

— Reply to this email directly or view it on GitHub https://github.com/naturalis/supersmart/issues/62#issuecomment-104653768 .

Diogo B. Provete, PhD.

PhD in Ecology and Evolution Postdoctoral Fellow (CNPq-Science without borders programme) Department of Biology and Environmental Sciences University of Gotenburg Gothenburg, Sweden

rvosa commented 9 years ago

Mmmm... sorry to hear you are having these issues. Unfortunately all of these have to do with Vagrant and/or VirtualBox so they are more or less outside of our control or expertise. Have you tried googling to see if other people experience the same things?

rvosa commented 9 years ago

We now have a wiki manual with the following sections:

It is therefore probably fair that this issue can now be closed.

alexantonelli commented 9 years ago

wonderful!!! Would be great to get any comments / feedback from users on that, even positive ones like ‘that’s all I needed’ :-)

Alex

Alexandre Antonelli http://antonelli-lab.net

On 05 Jun 2015, at 17:50 , Rutger Vos notifications@github.com<mailto:notifications@github.com> wrote:

We now have a wiki manual with the following sections:

It is therefore probably fair that this issue can now be closed.

— Reply to this email directly or view it on GitHubhttps://github.com/naturalis/supersmart/issues/62#issuecomment-109338465.

rvosa commented 9 years ago

Definitely. I assume this is going to be a bit iterative, with improvements coming for the run-through, and additional issues for the FAQ.

Today we added another one: your future student Amber came to the office, and we discovered our first case "in the wild" of a laptop disallowing all virtualization from inside its BIOS. We fixed it :)

On Fri, Jun 5, 2015 at 5:58 PM, Alexandre Antonelli < notifications@github.com> wrote:

wonderful!!! Would be great to get any comments / feedback from users on that, even positive ones like ‘that’s all I needed’ :-)

Alex

Alexandre Antonelli http://antonelli-lab.net

On 05 Jun 2015, at 17:50 , Rutger Vos <notifications@github.com<mailto: notifications@github.com>> wrote:

We now have a wiki manual with the following sections:

It is therefore probably fair that this issue can now be closed.

— Reply to this email directly or view it on GitHub< https://github.com/naturalis/supersmart/issues/62#issuecomment-109338465>.

— Reply to this email directly or view it on GitHub https://github.com/naturalis/supersmart/issues/62#issuecomment-109340649 .

diogoprov commented 9 years ago

Seems quite fair to me to close the issue. I think all the basics is there and everything we have encoutered in running it. The last thing I found out is that you have to do 'smrt exit' before killing the VM with 'vagrant halt'. As always, thank you for your support!