large function call confusion, commas, and semicolons
Jeff
Joined: 07/31/2009
We spoke about this before, but, as Bill pointed out recently, having blocks of code that cannot be evaluated (and that appears to be ending in commas) is going to be a source of confusion for users. Unless we place those pieces of code in the context of a large function call--by showing that large function call as one unit before the other pieces (and possibly referring to line numbers, which can be turned on)--we should probably just make use of variables in R.
We also have some irregular usage of semicolons in the documentation that needs addressed.
So the Optimization Script demo would be:
myExpMeanMatrix <- mxMatrix(
type="Full",
nrow=1,
ncol=2,
free=True,
values=c(0,0),
dimnames=list(NULL, selVars),
name="expMean"
)
myCholMatrix <- mxMatrix(
type="Full",
nrow=2,
ncol=2,
free=c(T,T,F,T),
values=c(1,.2,0,1),
dimnames=list(selVars, selVars),
name="Chol"
)
myExpCovAlg <- mxAlgebra(
expression=Chol %*% t(Chol),
name="expCov",
dimnames=list(selVars, selVars)
)
myData <- mxData(
observed=testData,
type="raw"
)
myObj <- mxFIMLObjective(
covariance="expCov",
means="expMean"
)
bivCorModel <- mxModel("bivCor", myExpMeanMatrix, myCholMatrix, myExpCovAlg, myData, myObj)
I think the confusion about
I think the confusion about "ending in a comma" obtains because people are not expecting functions with so many parameters... so it will pass promptly.
More enduringly, visual parsing is much easier when white-space indents are used
This is how I do mine:
http://pastie.textmate.org/private/zqy1iqxh9kwh5npztcsqq
It is then clear what is inside a function, and when the function call is over.
More use of explicit semi-colons also helps, as would a syntax coloring system: You could steal the one used in the pastie above.
PS: T ≠ True ≠ TRUE
Log in or register to post comments
In reply to I think the confusion about by tbates
You're right. One thing we
You're right. One thing we need to write is a better syntax highlighter for R for both the site and documentation. I'll add it a ticket for it.
Personally, I don't think we should use semicolons as they aren't really Rish.
And, actually, in R, T = = TRUE.
Log in or register to post comments
In reply to You're right. One thing we by Jeff
re: "actually, in R, T = =
re: "actually, in R, T = = TRUE"
> TRUE = FALSE
Error in TRUE = FALSE : invalid (do_set) left-hand side to assignment
> T = FALSE
> T==TRUE
[1] FALSE
>
Log in or register to post comments
I think it is a mistake to
I think it is a mistake to have unexecutable fragments in the yellow-backgrounded sections on pages like:
http://openmx.psyc.virginia.edu/docs/OpenMx/latest/Examples_Path.html#genetic-epidemiology-path-specification
It's not helpful or necessary.
Perhaps the standard should be that any yellow-section is copy and paste executable, and if the author wishes to draw attention to a small section which is not, then they should say "Thus the model can be names (see ‘share', line x below) instead of showing that fragment out of context.
Probably if exposition suggests breaking the function at a point which is not modular, then we might wish to re-factor or add a helper.
Log in or register to post comments
In reply to I think it is a mistake to by tbates
"Perhaps the standard should
"Perhaps the standard should be that any yellow-section is copy and paste executable...."
Agreed.
Log in or register to post comments
In reply to "Perhaps the standard should by Jeff
Agreed, but sometimes it will
Agreed, but sometimes it will be necessary to have already copy and paste executed prior slabs of code. Otherwise I think we'll need a different color in order to indicate that this slab is not copy-and-paste executable, because explaining a long script will naturally flip-flop between code fragments and descriptive text.
Log in or register to post comments
In reply to Agreed, but sometimes it will by neale
Important to keep the
Important to keep the occasions just to the necessary some-times's, not the more ubiquitous most times.
It would be useful if the docs showed the script is in one column, and when the user does a roll-over on a yellow-backgrounded piece, the full script scrolls to show the hight-lighted area. Not too hard to implement given line number support.
If the full script is formated using <p> as a line marker or similar, then the how-to page a javascript function to read in the desired paragraphs (lines) from the script on the fly, and create the rollover scroll, something like this (inchoate pseudo code)
<script type="text/javascript" charset="utf-8">
function makeYelloHelp (startLine, endLine, scriptFileURL) {
helpText = "<p class=\"yellowHelp\">";
var scriptLines =document.getElementsByTagName("p");
for(i=startLine; i<endLine;i++){
helpText + scriptLines[i];
};
// yellowHelp includes an on rollover behavior which scrolls to an anchor in the script and colors it
document.write(helpText);
}
</script>
that way the help writer just says a very english-like "as you can see in lines 10 through 12", except they write
As you can in <script makeYelloHelp(10,12,"mainscript" />
That also keeps things correct if the background script is edited.
Log in or register to post comments
In reply to Important to keep the by tbates
We're using Sphinx which
We're using Sphinx which allows us to compile pdfs automatically. The interactive solution doesn't seem to me to work so well in printed form. I would argue that how we solve this problem should work for both the printed and html doc and that it should be able to continue to be automatically compiled.
I think if we are careful about how we set up code blocks (perhaps as a fully executable codeblock first and then chunked and explained pieces afterwords) we can obtain the learning we desire without needing to resort to diverging interactive and printed versions.
Log in or register to post comments
In reply to We're using Sphinx which by Steve
Adding the full script at the
Adding the full script at the top, bottom, or along-side in a second column would certainly make thing much easier to follow, and maintain automation.
Log in or register to post comments
In reply to Important to keep the by tbates
While I am a big fan of
While I am a big fan of JavaScript and like your idea as an interface feature, I agree with Steve that this has to also work in printed form and add that it also has to work for those few users who have javascript-disabled/limited browsers. Providing the full block of code first and then referencing it via smaller blocks seems like it solves this problem. As a feature for all users, we can not only add line numbers to the full block, but have the smaller blocks display the numbers of the lines they were on in the larger block.
For instance, if the whole piece of code is 50 lines long, we might talk about one function call, displayed as follows:
...
The first argument of the code above creates an object of type mxMatrix as seen below....
33 mxMatrix(
34 type="Full",
35 nrow=1,
36 ncol=2,
37 free=True,
38 values=c(0,0),
39 dimnames=list(NULL, selVars),
40 name="expMean"
41 ),
...
The above code would be indented properly, however.
Log in or register to post comments
In reply to While I am a big fan of by Jeff
Line numbers help. I like
Line numbers help. I like that idea as long as we can make the line numbers be outside of the code block somehow so that the code block can still be cut and pasted without picking up the line numbers.
Log in or register to post comments