WaitUntilFlat: the HelpFile verbiage is unclear

[koganam]

ref: http://ninjatrader.com/support/helpG...tuntilflat.htm

What does this mean?

Warning: This property should ONLY bet set from the OnStateChange() method during State.SetDefaults or State.Configure

as, obviously, the example shows the property being queried in OBU.

I know what it is intended to say: it just does not say it.

Please specify exactly what property has to be set where, in the warning that you have penned.

I agree that it is a niggling detail, but help text must be so clear that it cannot be misunderstood.

Thanks.

[NinjaTrader_Jesse]

Hello,

Thank you for posting this.

I have submitted a request to have this page reviewed for clarity. Once I get any updates on that I will post back here.

I look forward to being of further assistance.

[NinjaTrader_DaveI]

I've changed the sentence to read: "Warning: This property should ONLY bet set from the OnStateChange() method during State.SetDefaults or State.Configure, although it can be read elsewhere."

I've expanded the warning to make it clear that setting should only be done there, while reading/querying can be done elsewhere.

[bltdavid]

I've changed the sentence to read: "Warning: This property should ONLY bet set from the OnStateChange() method during State.SetDefaults or State.Configure, although it can be read elsewhere."

I've expanded the warning to make it clear that setting should only be done there, while reading/querying can be done elsewhere.

bet set?

typo?

[bltdavid]

Also, that help page states,

"This property returns true if the strategy has detected it is either in a long or short position during start up; otherwise false."

What is the "it" referring to?

Isn't this property helping to differentiate between the account position vs strategy position?

Would it be better to say:

"This property returns true if the strategy has detected the account position is either in a long or short position during start up; otherwise false."

[bltdavid]

Another typo on that same page:

This statement,

"Determine is the strategy is currently waiting until a flat position is detected before submitting live orders."

Should be,

"Determine if the strategy is currently waiting until a flat position is detected before submitting live orders."

[koganam]

I've changed the sentence to read: "Warning: This property should ONLY bet set from the OnStateChange() method during State.SetDefaults or State.Configure, although it can be read elsewhere."

I've expanded the warning to make it clear that setting should only be done there, while reading/querying can be done elsewhere.

That is still somewhat unclear IMHO, as it seems to be implied that IsWaitUntilFlat is not itself set, or capable of being meaningfully set by the user, but rather a state variable that NT reads.

Maybe you should just move the caveat: "This property would only apply if the strategy StartBehavior was set to StartBehavior.WaitUntilFlat or StartBehavior.WaitUntilFlatSynchronizeAccount", from the description to become the warning?

[bltdavid]

That is still somewhat unclear IMHO, as it seems to be implied that IsWaitUntilFlat is not itself set, or capable of being meaningfully set by the user, but rather a state variable that NT reads.

Seems clear that this property can be meaningfully set by the user only "from the OnStateChange() method during State.SetDefaults or State.Configure".

Now, why one would even choose to set this property at all, and what happens under the hood when it is set to True or False during SetDefaults/Configure .. yes, that is very unclear.

I can agree with Koganam that IsWaitUntilFlat seems more like a read-only property, even the definition is stated in a way that makes it appear read-only.

If this variable is settable by the user, even if under limited circumstances, could the description please be updated to say what setting it to True or False is supposed to achieve?

[NinjaTrader_DaveI]

Although the property is settable (in any state <= State.Configure), if you actually tried to set it, there would be no noticeable results. Keep in mind that this property does not indicate the Start Behavior that is set, but rather indicates whether the strategy is currently waiting until flat because of the Start Behavior. Thus, if you were to set it to True in State.Configure, for example, then once State.Transition came around, the value of the property would be overwritten based on checks going on under the hood.

That last part is important to understand: In State.Transition (after Historical, before Realtime), if the strategy happens to be waiting until flat because of the configured start behavior, then IsWaitUntilFlat will be set to True, otherwise False.

I think you guys will like the updates to the help guide page based on this conversation. I've attached a screenshot of what it will look like.

[bltdavid]

I think you guys will like the updates to the help guide page based on this conversation. I've attached a screenshot of what it will look like.

Excellent.

Once the property is internally set to True or False inside State.Transition, will this property remain stuck at True or False forever?

[I presume the answer is yes, since the documentation implies at no other time is this property value ever set again]

[bltdavid]

Would you consider a small enhancement (aka nitpick)?

What exactly is the "it" referring to?
Account position?
Strategy position?

See my post here:

http://ninjatrader.com/support/forum/showpost.php?p=450613&postcount=5

Would it be wise/helpful to distinguish between account vs strategy position in the documentation for this property?

[NinjaTrader_DaveI]

The "it" refers to itself. The strategy detects whether it's position is flat or short.

The attached NS Output may help to clarify what is going to happen with the property value. If the start behavior is set to Wait Until Flat, then IsWaitUntilFlat will be False all the way up to State.Transition, then will change to False. Then, when it is no longer waiting for flat, it will switch back to False.

If the Start Behavior is not set to Wait Until Flat, then IsWaitUntilFlat will always be false. If the strategy is currently waiting until flat, the property will be True, and whenever it is not doing so, it will be False.

NinjaScript Output 3_3_2016 1_26 PM.txt

[koganam]

Although the property is settable (in any state <= State.Configure), if you actually tried to set it, there would be no noticeable results. Keep in mind that this property does not indicate the Start Behavior that is set, but rather indicates whether the strategy is currently waiting until flat because of the Start Behavior. Thus, if you were to set it to True in State.Configure, for example, then once State.Transition came around, the value of the property would be overwritten based on checks going on under the hood.

That last part is important to understand: In State.Transition (after Historical, before Realtime), if the strategy happens to be waiting until flat because of the configured start behavior, then IsWaitUntilFlat will be set to True, otherwise False.

I think you guys will like the updates to the help guide page based on this conversation. I've attached a screenshot of what it will look like.

[ATTACH]37613[/ATTACH]

That is just beautiful! Now it is absolutely clear, and incapable of being misunderstood. Thank you for your responsiveness.

One last quibble. Given the description, and obvious intent, and as it makes no sense for a programmer or user to set IsWaitUntilFlat, maybe you should explicitly make it incapable of being set? As a said, just a quibble. As long as it works and cannot be messed up by programmer or user, it is not a matter of real importance; more a matter of consistency: if setting it has no effect, then do not let it be set.

[NinjaTrader_Matthew]

That is just beautiful! Now it is absolutely clear, and incapable of being misunderstood. Thank you for your responsiveness.

One last quibble. Given the description, and obvious intent, and as it makes no sense for a programmer or user to set IsWaitUntilFlat, maybe you should explicitly make it incapable of being set? As a said, just a quibble. As long as it works and cannot be messed up by programmer or user, it is not a matter of real importance; more a matter of consistency: if setting it has no effect, then do not let it be set.

It must have a setter for internal purposes. The setter will throw an InvalidOperationException if a user does try to set it past State.Configure, which is why that error text was listed.

[bltdavid]

The "it" refers to itself. The strategy detects whether it's position is flat or short or long.

The attached NS Output may help to clarify what is going to happen with the property value. If the start behavior is set to Wait Until Flat, then IsWaitUntilFlat will be False all the way up to State.Transition, then will change to True. Then, when it is no longer waiting for flat, it will switch back to False.

Fixes in red, do you concur?

Ah, ok. You mean Position.MarketPosition, right?

In other words, during the period while IsWaitUntilFlat is True, the property Position.MarketPosition cannot and will not be MarketPosition.Flat, right?

Sort of like this code:

if (IsWaitUntilFlat && Position.MarketPosition == MarketPosition.Flat)
  Print("Stop the presses, this condition should be impossible");

Right?