Description
Issue Description
We need to better define the different meanings of "reset" to help explain reset_statepoint and update_statepoint. I've identified some places in the documentation with imprecise wordings.
Proposed change
I've copied the proposals here. See background for my reasoning.
- In Jobs-->The Job State Point-->Modifying the State Point, reword to not say "reset" like so: "
Job.reset_statepoint()will overwrite a job's existing statepoint file and change the job's directory name to be the newly determined hash while leaving other data files untouched." - In Modifying the State Point section of above, add examples to show the use of
update_statepointandreset_statepoint. - In The FlowProject-->The Project Status, reword to avoid the use of reset that is different from the function called reset: "We will remove the file that triggers our post condition label."
- Update description in signac core and link back to the relevant part of signac-docs (doc/bettter document update and reset statepoint signac#444)
Detailed Background
(1)
In Jobs-->The Job State Point-->Modifying the State Point we talk about reset_statepoint using the terminology of "resetting" as if it is self-evident:
The
Job.update_statepoint()method provides safeguards against accidental overwriting of existing state point values, whileJob.reset_statepoint()will simply reset the whole state point without further questions. (emphasis mine)
I see a few ways of interpreting this without looking at the source:
- Does it mean deleting all data in the job directory but the signac_statepoint.json?
- Everything but the statepoint and job doc?
- Does it mean leaving the data but changing the hash and directory name?
Looking at the source, we see that it means the last option.
(Item 1) I think the solution here is to reword to not say "reset": perhaps "Job.reset_statepoint() will overwrite a job's existing statepoint file and change the job's directory name to be the newly determined hash while leaving other data files untouched."
I think the confusion stems from the fact that signac.Job.reset() is a function, and it does get rid of data!
(2)
In Projects-->The Data Space-->Moving, Copying and Removal we distinguish job.reset() from job.clear() and job.remove() and here we find the clearest definition of job.reset():
the
reset()method will also clear all data associated with a job, but it will also automatically initialize the job if it was not originally initialized. (emphasis mine)
I think the wording here stays the same, but I'm including it to show the confusion as it relates to the previous example. In example (1), we change the statepoint data while preserving data. In example (2), we change the statepoint (by re-initializing it) and delete data!
(3)
In The FlowProject-->The Project Status, we see another use of the word "reset", this time referring to removing a specific piece of data:
We will reset the workflow for only a few jobs to get a more interesting status view.
Then the example shows manually removing the mock data file from the job.
(Item 3) Solution: reword to avoid the use of reset that is different from the function called reset: "We will remove the file that triggers our post condition label."
(1) again
Examples do not demonstrate use of update_statepoint() or reset_statepoint() even though update_statepoint is the suggested best practice. I raise this in this issue because it's mentioned in the same sentence as reset_statepoint() and the examples could help clarify both.
(Item 2) Solution: add examples to show these functions.
Possible related new issue: although technically, state point is not the same as a job, the job is identified by the hash of its statepoint, so it seems like resetting the statepoint could affect the job.
(Item 4) I will also make an issue to add more description to reset_statepoint in signac to better compare it to reset.