A class for interacting with the files associated with a given event. This class contains methods for working with these files individually (with FileHandlers) or as a group. In particular, the update method can be used to abstractly update the files in an event directory with the latest available information. This approach is robust and allows for trivial modifications and additions to the types of data files associated with events.
An event object, used to update and access data associated with a specific trigger (which recieves its own directory or
eventdir). FileHandler or another Event (or anything with ‘eventid’ and ‘rundir’ properties) as an input argument, in which case it will correspond to the same event as the object provided as an argument. One can also provide a module or dictionary containing FileHandlers, which will be used to create a
FileGraphfor the Event (i.e. it will specify which files should be made for this event). Defaults to the files module for now, though eventually this should be refactored out.
eventid_or_event (str or EventTuple or llama.filehandler.FileHandlerTuple) – This can be a string with the unique ID of this event (which can simply be a filename-friendly descriptive string for tests or manual analyses), in which case the next arguments,
pipeline, will be used; OR, alternatively, it can be an
FileHandlerinstance), or any object with valid
rundirattributes. In this case, those attributes from the provided object will be re-used, and the
rundirargument will be ignored. This makes it easy to get a new
Eventinstance describing the same underlying event but with a different
Pipelinespecified, or alternatively to get the
Eventcorresponding to a given
FileHandler(though in this case you should take care to manually specify the ``Pipeline`` you want to use!).
rundir (str, optional) – The
rundir, i.e. the directory where all events for a given run are stored, if it differs from the default and is not specified by
pipeline (llama.pipeline.Pipeline, optional) – The
pipeline, i.e. the set of FileHandlers that we want to generate, if it differs from the default pipeline. If none is provided, use
event – A new
Eventinstance with the given properties.
- Return type
ValueError – If the
eventid_or_eventargument does not conform to the above expectations or if the
rundirdirectory for the run does not exist, a ValueError with a descriptive message will be thrown.
Names of possible auxiliary paths in the directory that are used to track the state of the Event as a whole.
The time at which the permissions of this event directory were last changed (according to the underlying storage system). Note that you probably are more interested in
clone(commit='HEAD', rundir=None, clobber=False)¶
Make a clone of this event in a temporary directory for quick manipulations on a specific version of a file.
commit (str, optional) – The commit hash to check out when cloning this event. If not specified, the most recent commit will be used. Unsaved changes will be discarded.
rundir (str, optional) – The run directory in which to store the cloned event. If not specified, a temporary directory will be created and used. The contents of this directory will NOT be deleted automatically.
clobber (bool, optional) – Whether this cloned event should overwrite existing state.
clone_event (llama.event.Event) – A clone of this event. The full history is saved, but the specified
commitis checked out. Any uncommitted changes in the working directory will not be copied over to the
clone_eventalready seems to be a valid event with the correct
commithash, no further action will be taken (thus repeated cloning has little performance penalty).
llama.versioning.GitRepoUninitialized – If this is called on an
Eventthat has not had its git history initialized.
IOError – If this event already exists in the specified
rundirand is checked out to a different hash, unless
clobberis True, in which case that working directory will be deleted and replaced with the desired commit.
Compare the file contents of this event to another event using
filecmp.cmpfiles(though results are given as
FileHandlerinstances rather than file paths). Use this to see whether two event directories contain the same contents under a given pipeline.
other (Event, str) – The other
Eventinstance to compare this one to, or else a directory containing files that can be compared to this
Event(though in that case the filenames must still follow the expected format).
match (FileGraph) – A
Eventwhose files have the same contents as those corresponding to the
mismatch (FileGraph) – A
Eventwhose files have differing contents as those corresponding to the
errors (FileGraph) – A
Eventwhose corresponding files do not exist or otherwise could not be accessed for comparison (either for the files corresponding to this
ValueError – If the
Pipelineinstances of this
otherone are not equal, it does not make sense to compare them, and a
ValueErrorwill be raised.
Return a list of files in the event directory that are not associated with any file handler nor with event state directories.
The full path to the directory containing files related to this event.
Check whether this event already exists.
FileHandlerinstances for the files in this event with this particular
Initialize an event just by providing a filepath to its event directory. If no directory is specified, default to the current directory and try to treat that like an event. Note that the returned event will eliminate symbolic links when determining paths for
eventid. Useful for quickly making events during interactive work.
eventdir (str, optional) – The event directory from which to initialize a new event.
**kwargs – Remaining keyword arguments to pass to
Return the GPS time of this event. Returns -1 if none can be parsed.
Initialize the directory for this event, making sure it is in a proper state for processing data. Make sure the
eventdirexists by creating it if necessary. Also initializes version control and set flags to the defaults specified in
Eventinstance to allow command chaining.
- Return type
ValueError – If the
eventdirpath exists but is not a directory or a link to a directory, we don’t want to overwrite it to make an the directory.
The time at which this event directory was modified (according to the underlying storage system).
printstatus(cruft=False, highlight=None, unicode=True, plot=None)¶
Get a user-readable message indicating the current status of this event. Include a list of files not in the selected pipeline with
cruft=True. Bold lines in the summary table containing strings in
highlightas substrings. Use nice unicode characters and terminal colors with
unicode=True, or use plain ascii with
unicode=False. Include a status graph plot with
plot=True, or exclude it with
plot=None, include the plot only if the underlying
Graph::EasyPerl library is available on the host.
Save this event and all its contents as a gzipped tarball. You should probably use a
.tar.gzextension for the
Generate any files that fit the
FileGraphdownselection criteria specified in
downselect. By default, generate all files that have not been generated and regenerate all files that have been obsoleted because their data dependencies have changed. Returns
Trueif files were updated,
Falseif no files in need of update were found.
Return the timestamp of the first file version commit, catching the error if the event does not have versioning initialized/has no versions and returning
EventTuple(eventid, rundir, pipeline)¶
Alias for field number 0
Alias for field number 2
Alias for field number 1
Returns new datetime object representing current time local to tz.
If no tz is specified, uses local timezone.