ross.csv documentation

[markplagge]

I would love to have a header file or some sort of column title for the ross.csv file that is generated. It gets challenging to use this file after a few runs. Or even a brief description of what the columns are would be very helpful.

[gonsie]

Honestly, I've never even looked at the ross.csv file. Is a per-run generated file useful to you? What sort of information should be included in this file?

[markplagge]

In my model, I actually use the code in ross-stats to output some useful data to stderr to catch with a script. However, sometimes I realize that I need information like percent remote events, efficiency, ROSS kernel options, and other stuff. I was hoping that ross.csv contained all of the run time information from the previous ROSS run. Personally, I would find this useful since sometimes I need info that I forgot to include in my custom stats output. CSV works really well since I can just dump it into whatever program I need to check it. The perfect ROSS CSV file would contain:

• The command used to run this instance of ROSS
• All of the stats displayed at the end of the run
• Error status if ROSS failed with some memory issue
• The time/date of the run

To me it makes sense that a ross.csv file would contain a big dump of ROSS runtime info for each run. Having it be nondestructive (as it seems to be now) would also be great.

[gonsie]

In part, you are also asking for #30. So, since I'm going to overhaul how ROSS output is handled, how do these options sound:

1. the option to pretty-print the run-time options:
   • to stdout
   • destructively to a specified file (name specified by the model developer)
   • or not at all
2. the option to pretty-print the end statistics:
   • to stdout
   • destructively to a specified file (name specified by the model developer)
   • or not at all
3. the option to CSV print run-time options, non-destructively to a CSV file (would only include ROSS core/kernel options aka would not include model options or RIO/other component options). Should this really be an option that the user can turn off?
4. the option to CSV print end statistics (or end-status), non-destructively to a CSV file (would only include ROSS core statistics aka would not include model statistics). Should this really be an option that the user can turn off?

Each option would be separate, so you could choose any combination of the 4 above. Note: For 1 and 2, I could add a timestamp to a specified filename (to make it non-descructive) Note: For 3 and 4, API could easily be improved as to incorporate model registered options/stats, but I'll save that for later.

[JohnPJenkins]

Those options look great to me! I've never looked at ross.csv either :). As for defaults, I'd prefer opt-in behavior, i.e. no output unless the user asks for it.

Perhaps you can use 4 toggles:

--pretty-env=<file>
--pretty-stat=<file>
--csv-env=<file>
--csv-stat=<file>

where file is some path - no option prints to stdout, whereas "stdout" and "stderr" arguments print to stdout/stderr, respectively. It's useful to be able to keep stdout clean for parsing user-defined output. You can check for file(s) existence at startup and error out if they exist.

Unique suffixes should be opt-in as well I think, with an option such as --unique-output-suffix option (or similar). When I run model ensembles, I'm already separating the filenames. Uniqueness ends up being useful for the edit/debug cycle.

[gonsie]

The CSV printing will be an ON/OFF option only. If we want the power to append to the CSV file, we'll have to attempt to ensure that the actual number/order of command-line options doesn't change. So, ROSS will create CSV files per version: ross-#hash#-clo.csv (command-line options) and ross-#hash#-end.csv (end state: stats or error msg).

As for opt-in behavior, we can certainly do that with sometime like --csv. It might be best to keep the two CSV files linked with the same flag, that way each line in the clo file matches a line in the end file.