large function call confusion, commas, and semicolons

11 replies [Last post]
Jeff's picture
Offline
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)

tbates's picture
Offline
Joined: 07/31/2009
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#ge...

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.

Jeff's picture
Offline
Joined: 07/31/2009
"Perhaps the standard should

"Perhaps the standard should be that any yellow-section is copy and paste executable...."

Agreed.

neale's picture
Offline
Joined: 07/31/2009
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.

tbates's picture
Offline
Joined: 07/31/2009
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.

Jeff's picture
Offline
Joined: 07/31/2009
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.

Steve's picture
Offline
Joined: 07/30/2009
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.

Steve's picture
Offline
Joined: 07/30/2009
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.

tbates's picture
Offline
Joined: 07/31/2009
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.

tbates's picture
Offline
Joined: 07/31/2009
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

Jeff's picture
Offline
Joined: 07/31/2009
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.

tbates's picture
Offline
Joined: 07/31/2009
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
>