[Bilka] [0.17.43] _statistics input and output documentation confusing

[Qon]

input means output & output means input

If I ask for outputs of of machines with:

Code: Select all

serpent.block(game.player.force.item_production_statistics.output_counts)

Then I get a nice table listing the input materials consumbed by entities.

input_counts gives me the production output stats.

Left is right and right is wrong.

Last printout here is shown with command used to print it while also showing the stats.

ousu(190529-154603-46).jpg (565.47 KiB) Viewed 2576 times

This flip is the same for other LuaFlowStatistics things I've tested also, like

Code: Select all

game.pollution_statistics

. And it is also swapped for

Code: Select all

get_flow_count

where input = true gives output and vice versa.

[Rseding91]

Thanks for the report however that's working as intended: "input" is positive values (items produce) and output is negative values (things consumed). Except for power which is the other way around.

[Qon]

When I read the documentation I see this:

get_input_count(string) → uint64 or double
Gets the total input count for a given prototype.
Parameters
string: The prototype name.

get_output_count(string) → uint64 or double
Gets the total output count for a given prototype.
Parameters
string: The prototype name.

It isn't mentioned that input means output and that output means input. And it doesn't make sense just because "input is positive" and "output is negative".
You can just as easily say that "output is positive and input is negative". But if you try to interpret the names with an understanding of the meaning of the English words you get the opposite interpretation of their meaning according to an English dictionary. I don't understand how this is not a bug...

Except for power which is the other way around.

Are you just trolling me now or are you actually serious?
So input means output, but only sometimes?
And it isn't documented!?

on_flow is clue:

count :: float: The count: positive or negative determines if the value goes in the input or output statistics.

If you interpret positive and negative having the same order as the in/out they are related to as stated after. But it isn't explicitly stated. And it is only sometimes true!

[AlFara]

I have to admit, it's a bit confusing.
So, if i input a pizza (piece by piece) into my body by inserting it into the mouth, it processes the pizza and outputs the result of the process.

If it's working different here and it's intended, please add, like Qon mentioned, an information to the wiki to prevent confusion, mb like "this means that here because [input reason here]"

[Rseding91]

The English names for the storage of the positive and negative values is mostly noise and if possible I would retroactively remove the name and just call it "positive values" and "negative values".

They have no relation to what's actually stored in them past that distinction.

For example: electric networks store values in the opposite groups because it makes the GUI read nicer.

[Rseding91]

I have to admit, it's a bit confusing.
So, if i input a pizza (piece by piece) into my body by inserting it into the mouth, it processes the pizza and outputs the result of the process.

If it's working different here and it's intended, please add, like Qon mentioned, an information to the wiki to prevent confusion, mb like "this means that here because [input reason here]"

The naming follows "input == add", "output == remove". You "add" by storing positive values to "input" and "remove" by storing negative values to "output". Again, the names are mostly meaningless. I would change them but I consider braking every mod that uses those functions a stupid idea and so the names stay.

[AlFara]

i agree, it's better to leave it as it is then.
will you link this topic or edit the description on the nessesary lua site in the near future so it's clear that players regard those values with caution? i think, the place where "Encapsulates statistic data for different parts of the game" would be a good place to add another sentence for clarification while keeping the method descriptions short and solid^^

-edit-
@bilka's post below: thank you very much

[Bilka]

I took the liberty to see this as a documentation bug, and fixed the documentation for the next version. In short, the easiest way to find out what input and what output is, is to look at the GUI for the statistics. Input is on the left, output on the right. I documented it as such, including some examples.

[Qon]

The naming follows "input == add", "output == remove". You "add" by storing positive values to "input" and "remove" by storing negative values to "output". Again, the names are mostly meaningless. I would change them but I consider braking every mod that uses those functions a stupid idea and so the names stay.

Well, at least they aren't named with the intention of causing maximal Qonfusion
I can appreciate both good names that are well documented and not getting my mods broken so I understand a bit of reluctance to change it.

I took the liberty to see this as a documentation bug, and fixed the documentation for the next version. In short, the easiest way to find out what input and what output is, is to look at the GUI for the statistics. Input is on the left, output on the right. I documented it as such, including some examples.

Thanks
Is this true for electric networks also, or did I misunderstand Rseding91?

Thanks for the report however that's working as intended: "input" is positive values (items produce) and output is negative values (things consumed). Except for power which is the other way around.

So is "input = negative, on the left" or is "input = negative, on the right". Or maybe it is "input = positive, on the right" because production is on the right for electric networks (my current guess)?

And why is production on the right in the GUI for electric networks when it is on the left for everything else?

Also, am I correct to assume that this documentation fix will appear at https://lua-api.factorio.com/latest/Lua ... stics.html ? Are there other places where this will be documented, like `game.pollution_statistics` (which links to LuaFlowStatistics) if different flow stat usage has it "the other way around" (depending on what that means)?

[Bilka]

Is this true for electric networks also, or did I misunderstand Rseding91?

It's also true there, open it up in-game and you see that the energy consumption is on the left (and thus input), which leads to your confusion.

And why is production on the right in the GUI for electric networks when it is on the left for everything else?

Also, am I correct to assume that this documentation fix will appear at https://lua-api.factorio.com/latest/Lua ... stics.html ?

I think the electric network GUI is different because it is "more useful" to have the consumption on the left, the "primary" side (we read left to right). There is much more information to be found in the >10 machines that are consuming compared to the max 4 that are producing.

And yes.