"design" ==> "specification"

[benthestatistician]

Let's update our nomenclature as follows.

• [x] Rename: rct_design(), rdd_design()==> rct_spec(), rdd_spec(); as_rct_design(), as_rdd_design() ==> as_rct_spec(), as_rdd_spec().
• [x] Add alias rct_spec -> rct_specification , rdd_spec -> rdd_specification.
• [x] Rename obs_design() ==> obs_spec().
• [x] Add aliases obs_specification -> obsstudy_specification -> obsstudy_spec -> obs_spec.
• [x] Rename "Design" class as "StudySpecification".
• [x] Rename "design=" argument of lmitt.formula() as specification=.
• [x] Corresponding updates as appropriate in tests/testthat/.
• [x] Replace function/argument/class names in Documentation.
• [ ] Update documentation to discuss "specifications" rather than "designs".

Rationale:

• When I talk about the package or sit down to write about it I find "design" a bit forced and a bit ambiguous.
• The survey package already has a "design" concept, with corresponding functions and object names. Also our own meerkt package has a "Design" object and concept, as does RItools. So I think switching away from this now will stave off future developer confusion.

[josherrickson]

@jwasserman2 @xinhew0708 I plan to start tackling this this afternoon. This is going to be a seismic change to the repo, so if anyone has any outstanding branches they'd like to get merged in today first, please speak up now so I can hold off.

[josherrickson]

Completed

• *_design is now *_spec. (I haven't added any aliases yet.)
• Design is now StudySpecification
• The design= argument to all functions (including lmitt) is now specification=.
• Anywhere we were using des or similar, renamed to spec or similar. (e.g. desmod -> specmod). I did this as carefully as I could, but it's possible you'll see a few "provispec" in the comments/documentation.
• All files are also renamed.
• Vignettes/articles/developer_docs are updated as well
  • I did not test run any developer_docs

Outstanding

• [x] Aliases (hoping to get to that shortly)
• [ ] DESCRIPTION - I did a quick find/replace on the Title/Description in DESCRIPTION, but it could use a pass just to make sure the language still makes sense. @benthestatistician
• [ ] I did not do a pass to make sure documentation still reads well.

Technical details

I did four substitutions

1. _design to _spec
2. Design to StudySpecification
3. design to specification
4. des to spec
5. (Technically a few more smaller ones like d <- rct_spec... is not spec <- rct_spec.)

The first three were done programmatically. It should cause no issues with code, but it could have caused issues with text (e.g. a sentenced reading "Design your study carefully." would now say "StudySpecification your study carefully."). E.g.

find R/ -type f -exec sed -i '' s/_design/_spec/g {} +

The fourth and below were done semi-manually; I gave each file a brief spot check to ensure des only appeared where I wanted to make a change, e.g.

grep spec tests/testthat/test.SandwichLayer.R

taking note of any lines I saw where I didn't want to make the change, the running the appropriate find command, followed by manually fixing the noted lines.

[josherrickson]

@benthestatistician I just noticed that we had previously rd_design. Your list above specifies renaming rdd_design to rdd_spec. Do you want rdd_spec or rd_spec?

[benthestatistician]

Let's stick with "rd_", ie go to rd_spec. (Sorry for the oversight.)

[josherrickson]

This felt large enough for a minor bump, just to be able to point to a clear change point in language.

[jwasserman2]

Some of the language in the intro-to-propertee vignette now reads somewhat awkwardly with the one-to-one replacement (brought to my attention by some questions from Cassandra). Flagging that if we continue to use that as the primary document for users, I think we'll want to revise some of the phrasing.

Also, it looks like the MI vignette isn't populating on the website after the recent push. Can you check that out, Josh?

[josherrickson]

@jwasserman2 see my 2nd to last comment in #70 - It's on my list to address when I get a chance.