search

macroevolution / bamm

A program for multimodel inference on speciation and trait evolution
GNU General Public License v2.0
33 stars 10 forks source link

sphinx: postprocess documentation, critical eyes needed #90

Closed drabosky closed 10 years ago

drabosky commented 10 years ago

Need someone (or several people) who are not me go through two main BAMMtools documentation sections: postprocess and rateshifts. See if these examples work as coded in sphinx and if you can follow this and if the links work. These sections are done.

You'll need to make the documentation anew from the bamm/doc directory by typing make html this will create html files in the doc/source directory that you can examine.

drabosky commented 10 years ago

OK, I finished this. It should be ready for critical review. I am guessing that some of the examples and code on the bamm graph gallery should be updated but I will leave this for the moment.

redcurry commented 10 years ago

In section 6.4, it provides commands to discard the burnin, yet the the getEventData function has a burnin parameter (which is not described), that I figured did this for me.

drabosky commented 10 years ago

Right....6.4 is working with the raw mcmc output file, getEventData with the event data file, so they are different. But if it is unclear we should fix it.

On Mar 3, 2014, at 3:38 PM, Carlos Anderson wrote:

In section 6.4, it provides commands to discard the burnin, yet the the getEventData function has a burnin parameter (which is not described), that I figured did this for me.

— Reply to this email directly or view it on GitHub.

redcurry commented 10 years ago

Oh, you're right. Maybe add to what you already have... "we’ll discard the first 10% of samples as burnin (the same amount as we did for the event data):"

redcurry commented 10 years ago

I'm beginning to see why someone wanted to delete the ">" before R commands. I can't copy and paste a block of R code from the documentation because the ">" are also copied and R doesn't understand them.

drabosky commented 10 years ago

I think in general that it is not good practice with R to copy and paste code, for several reasons (cryptic characters being among them). So, I'm not sure we want to encourage it. Sweave is the standard R documentation, and the intention is to show code chunks as they are typed in the console rather to give users something to copy and paste without thinking. That's another issue...it's probably good to at least try and force people to understand what they are typing since they are going to have to do exactly the same with their own data. So, my vote is to keep the ">" brackets

On Mar 3, 2014, at 4:43 PM, Carlos Anderson wrote:

I'm beginning to see why someone wanted to delete the ">" before R commands. I can't copy and paste a block of R code from the documentation because the ">" are also copied and R doesn't understand them.

— Reply to this email directly or view it on GitHub.

redcurry commented 10 years ago

Ok, good points!

redcurry commented 10 years ago

In the last part of section 7.8, the examples switched to being about traits. I was not able to test the code as is because all my variables are based on speciation/extinction (I had to change beta to lambda to make it work). I would keep all examples consistent if someone is following along the text from top to bottom.

drabosky commented 10 years ago

Hmm, not sure what to do about this. If I follow the line you are referring to, the text says:

"If your rate matrix was for trait evolution, you will have a component rtt$beta in your rtt object (components rtt$lambda and rtt$mu if you are modeling speciation-extinction). To get the mean rates at any point in time:"

so the point is to explain to the user how they would work with traits, not lead them through a full example.

On Mar 4, 2014, at 2:49 PM, Carlos Anderson wrote:

In the last part of section 7.8, the examples switched to being about traits. I was not able to test the code as is because all my variables are based on speciation/extinction (I had to change beta to lambda to make it work). I would keep all examples consistent if someone is following along the text from top to bottom.

— Reply to this email directly or view it on GitHub.

redcurry commented 10 years ago

Yeah, but I would have preferred that the code shown be about lambda (or mu) because the code is doing something new we haven't done before with speciation/extinction. The text about the rate maxtrix possibly being about trait evolution is fine, as that would signal the user that lambda can be replaced by beta to get the mean rates about beta.