Measure writing guide: add section about I/O file + modernize #25

jmarrec · 2021-06-03T12:26:55Z

Measure writing guide: add section about I/O file + modernize

… of Ruleset

jmarrec · 2021-06-03T12:27:41Z

docs/reference/measure_writing_guide.md

+Please note the original namespace in versions of OpenStudio < 2.X `OpenStudio::Ruleset` is deprecated and replaced with `OpenStudio::Measure`.
+Measure classes prior to 2.X are also deprecated:
+
+| < 2.X (Deprecated)                       | >= 2.X                            |
+|------------------------------------------|-----------------------------------|
+| OpenStudio::Ruleset::ModelUserScript     | OpenStudio::Measure::ModelMeasure |
+| OpenStudio::Ruleset::WorkspaceUserScript | OpenStudio::Measure::ModelMeasure |


I did some changed re OpenStudio::Ruleset > OpenStudio::Measure

jmarrec · 2021-06-03T12:27:49Z

docs/reference/measure_writing_guide.md

+    args = OpenStudio::Measure::OSArgumentVector.new
+    insl_thckn = OpenStudio::Measure::makeDoubleArgument('insl_thckn',true)


One of many

jmarrec · 2021-06-03T12:28:02Z

docs/reference/measure_writing_guide.md

+### Reporting Measure arguments Method
+
+```ruby
+def arguments(model = nil)
+```
+


jmarrec · 2021-06-03T12:28:26Z

docs/reference/measure_writing_guide.md

+### Outputting a HTML (or other) file
+
+You can create any file in the current working directory named `report*.*` and it will be copied over to the `reports/` directory via the openstudio-workflow gem.
+The name of the resulting file is computed from the measure class name and the filename.
+
+If your measure class name is `ReportingMeasureName`:
+
+```ruby
+
+class ReportingMeasureName < OpenStudio::Measure::ReportingMeasure
+
+  [...]
+
+  def run(runner, user_arguments)
+    super(runner, user_arguments)
+
+    # Outputs to: reports/reporting_measure_name_report_one.html
+    File.open('./report_one.html', 'w') do |file|
+      # Write file
+    end
+
+    # Outputs to: reports/reporting_measure_name_qa_qc.csv
+    File.open('./qa_qc.csv', 'w') do |file|
+      # Write file
+    end
+  end
+end
+
+FooBar.new.registerWithApplication
+```
+
+


Document the classic case: output a report file from a ReportingMeasure.

jmarrec · 2021-06-03T12:29:25Z

docs/reference/measure_writing_guide.md

+## Using files and using ExternalFile in a measure
+
+It is sometimes needed to create support files in the process of running the measure. This section describes how path handling works in the context of a measure.
+
+When running a measure, the current working directory is something like './run/000_measure_class_name/' (this is the output that `File.realpath('./')` will give you).
+None of the files created in this directory will actually be copied over, unless it is the special case described in the section 'Reporting Measures' > 'Outputting an HTML (or other file)'.
+
+### Measure resource files
+
+#### Where to place them
+Resource files for a measure should be placed in the `resources/` subfolder like the Measure File Structure section indicates to do with additional ruby code.
+Note that nested levels are not accepted, meaning that given the below tree, anything in `resources/subfolder` is not valid: `anotherschedulefile.csv` will not be copied over with the measure.
+
+```
+├── measure.rb
+├── measure.xml
+├── resources
+│   ├── schedulefile.csv
+    │   ├── subfolder
+    │   │   ├── anotherschedulefile.csv
+```
+
+#### How to access them inside a measure
+
+You can locate your measure resources by using a relative path to the `measure.rb` you are running by using `File.join(File.dirname(__FILE__), 'schedulefile.csv')`
+
+#### How to use an ExternalFile inside a measure
+
+The constructor for `ExternalFile` will automatically copy the file at the path you provide to the first element in `WorkflowJSON::filePaths[0]`. When running a measure, the openstudio-workflow gem prepends the `generated_files` subdirectory.
+
+```ruby
+class CreateScheduleFile < OpenStudio::Measure::ModelMeasure
+
+  [...]
+
+  def run(model, runner, user_arguments)
+
+    # Locate the resource file (this resolves to something like './measures/resources/schedulefile.csv')
+    csv_in_path = File.join(File.dirname(__FILE__), 'schedulefile.csv')
+
+    # Instantiate an External File: this will automatically copy to first path in WorkflowJSON: `runner.workflow.filePaths[0]`, typically './generated_files/'
+    externalFile_ = OpenStudio::Model::ExternalFile::getExternalFile(model, csv_in_path)
+    if (!externalFile_)
+      runner.registerError("Failed to instantiate an External File")
+      return false
+    end
+
+    column = 1
+    rowsToSkip = 1
+    scheduleFile = OpenStudio::Model::ScheduleFile.new(externalFile_.get(), column, rowsToSkip)
+    scheduleFile.setName("ExampleScheduleFile")
+
+    return true
+end
+```


This section is fair game and general enough. I definitely think it should be added.

jmarrec · 2021-06-03T12:29:57Z

docs/reference/measure_writing_guide.md

+#### How to output any other file
+
+To output any file you may need that isn't an `ExternalFile`, you should rely on two things, in order of preferences:
+* `runner.workflow.filePaths[0]`: this will typically resolve to `./generated_files`
+* `runner.workflow.absoluteRootDir`: this will resolve to '.'
+
+`.` is the location defined as the `root` key inside the `workflow.osw`, or if not specified the location of the `workflow.osw` itself.


I find that relevant, but it's possible other people might not?

jmarrec · 2021-06-03T12:30:12Z

docs/reference/measure_writing_guide.md

+    # Locate the resource file (this resolves to something like './measures/resources/schedulefile.csv')
+    csv_in_path = File.join(File.dirname(__FILE__), 'schedulefile.csv')
+
+    # Canonical way: write to the ./generated_files directory
+    out_file = File.join(runner.workflow.filePaths[0].to_s, 'myfile.csv')
+    File.open(out_file, 'w') do |f|
+      f << "Hello"
+    end


I think that part is definitely fine.

jmarrec · 2021-06-03T12:31:57Z

docs/reference/measure_writing_guide.md

+    # Prefer the above, but one valid use case would be to output to the reports/ folder
+    # (this is a *ModelMeasure*, you cannot just name it './report.html'
+    # and have it copied automatically like described above in Reporting measure section)
+
+    # either /tmp/osmodel-1622719126-1/ApplyMeasureNow
+    # or ./<model_companion_dir>/
+    rootDir = runner.workflow.absoluteRootDir.to_s
+
+    html_out_path = 'report.html'
+    if (File.basename(rootDir) == 'ApplyMeasureNow')
+      html_out_path = File.absolute_path(
+        File.join(rootDir, '..', 'resources', 'reports', html_out_path))
+    else
+      html_out_path = File.absolute_path(
+        File.join(rootDir, 'reports', html_out_path))
+    end
+    outDir = File.dirname(html_out_path)
+    if !File.exists?(outDir)
+      FileUtils.mkdir_p(outDir)
+    end
+    File.open(html_out_path, 'w') do |f|
+      f << "<html><head><title>My Custom Report that works with Apply Now!</title></head><body><h1>Hello World!</h1></body></html>"
+    end


So perhaps this section is overkill or an invitation for bad ideas. I don't know. But people are definitely already doing stuff like this (cf discussion on NREL/OpenStudio#4046) except they are not doing it right for lack of documentation.

jmarrec · 2021-06-03T12:32:23Z

docs/reference/measure_writing_guide.md

+Regarding Note A in the above code, note that this is added to the `WorkflowStepResult` `step_files` entry (WorkflowJSON: root > "steps" [] > "result" > "step_files", see [Workflow JSON schema](https://github.com/NREL/OpenStudio-workflow-gem/blob/e569f910be364d33c3ddb1a655570c85f1b24bfa/spec/schema/osw_output.json#L251))
+
+It possible to capture the path to the stepFiles from a previous step inside a measure like the following:
+
+```ruby
+    if runner.workflow.currentStepIndex() > 0
+      previousStep = runner.workflow.workflowSteps[runner.workflow.currentStepIndex() - 1]
+      if previousStep.result
+        previousStepResult = previousStep.result.get
+        runner.registerWarning("previousStepResult.stepFiles=#{previousStepResult.stepFiles.map{|p| p.to_s}}")
+      end
+    end
+```


I don't have a good use case for this but perhaps @DavidGoldwasser might. I won't be offended if you don't lik that section

…e Template In conjunction with NREL/OpenStudio-user-documentation#25

tijcolem · 2021-06-21T15:54:15Z

@jmarrec Changes look good. Thanks for the updates. I just assigned this to myself. I'd like to build/convert the docs to html before merging to gh-pages branch.

tijcolem · 2021-06-21T16:26:02Z

Looks good served up locally using mkdocs.

jmarrec added 3 commits June 3, 2021 14:11

Add documentation for handling input/output files in measure

353e729

cf NREL/OpenStudio#4046

Update measure writing guide to use the new Measure namespace instead…

0ea28c1

… of Ruleset

bump toc for OS app (unrelated, but 1.2.0 is imminent)

d9d7ac8

jmarrec commented Jun 3, 2021

View reviewed changes

jmarrec added a commit to NREL/OpenStudio that referenced this pull request Jun 3, 2021

In conjunction with NREL/OpenStudio-user-documentation#25

0ca847e

jmarrec added a commit to NREL/OpenStudio that referenced this pull request Jun 3, 2021

#4046 - Clarify the situation with output file in the ReportingMeasur…

aae01b9

…e Template In conjunction with NREL/OpenStudio-user-documentation#25

This was referenced Jun 3, 2021

#4046 - Clarify the situation with output file in the ReportingMeasure Template NREL/OpenStudio#4345

Merged

Schedule CSV written in measure is not found NREL/OpenStudio#3609

Closed

tijcolem self-assigned this Jun 21, 2021

tijcolem merged commit 14154eb into NREL:master Jun 21, 2021

tijcolem added a commit that referenced this pull request Jun 21, 2021

Updated for #25

28f4d4b

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Measure writing guide: add section about I/O file + modernize #25

Measure writing guide: add section about I/O file + modernize #25

jmarrec commented Jun 3, 2021 •

edited

Loading

jmarrec Jun 3, 2021

jmarrec Jun 3, 2021

jmarrec Jun 3, 2021

jmarrec Jun 3, 2021

jmarrec Jun 3, 2021

jmarrec Jun 3, 2021

jmarrec Jun 3, 2021

jmarrec Jun 3, 2021

jmarrec Jun 3, 2021

tijcolem commented Jun 21, 2021

tijcolem commented Jun 21, 2021

		args = OpenStudio::Measure::OSArgumentVector.new
		insl_thckn = OpenStudio::Measure::makeDoubleArgument('insl_thckn',true)

Measure writing guide: add section about I/O file + modernize #25

Measure writing guide: add section about I/O file + modernize #25

Conversation

jmarrec commented Jun 3, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tijcolem commented Jun 21, 2021

tijcolem commented Jun 21, 2021

jmarrec commented Jun 3, 2021 •

edited

Loading