Movies – Reference

Class MovieTabular

    A "tabular movie" is a list of snapshots of data that comes as a python dictionary
    (representing a list of values and their corresponding names),
    such as something based on the state of the system or of parts thereof,
    either taken at different times,
    or resulting from varying some parameter(s)

    Each snapshot - incl. its parameter values and optional captions -
    will constitute a "row" in a tabular format

    MAIN DATA STRUCTURE for "tabular" mode:
        A Pandas dataframe

name

arguments

returns

__init__

self, parameter_name="SYSTEM TIME"

        :param parameter_name:  A label explaining what the snapshot parameter is.
                                Typically it's "SYSTEM TIME" (default), but could be anything
                                Used as the Pandas column name for the
                                parameter value attached to the various snapshot captures

name	arguments	returns
__len__	self	int
Return the number of snapshots comprising the movie :return: An integer

name	arguments	returns
__str__	self

name	arguments	returns
store	self, par, data_snapshot: dict, caption=""	None
Save up the given data snapshot, alongside the specified parameter value and optional caption EXAMPLE : store(8., {"A": 1., "B": 2.}, "State immediately before injection of 2nd reagent") :param par: Typically, the System Time - but could be anything that parametrizes the snapshots (e.g., a dictionary, or any desired data structure.) It doesn't have to remain consistent, but it's probably good practice to keep it so :param data_snapshot: A dict of data to preserve for later use :param caption: OPTIONAL string to describe the snapshot :return: None (the object variable "self.movie" will get updated)

name

arguments

returns

store

self, par, data_snapshot: dict, caption=""

None

        Save up the given data snapshot, alongside the specified parameter value and optional caption

        EXAMPLE :
                store(8., {"A": 1., "B": 2.}, "State immediately before injection of 2nd reagent")

        :param par:             Typically, the System Time - but could be anything that parametrizes the snapshots
                                    (e.g., a dictionary, or any desired data structure.)
                                    It doesn't have to remain consistent, but it's probably good practice to keep it so
        :param data_snapshot:   A dict of data to preserve for later use
        :param caption:         OPTIONAL string to describe the snapshot
        :return:                None (the object variable "self.movie" will get updated)

name	arguments	returns
get_dataframe	self, head=None, tail=None, val_start=None, val_end=None, search_col=None, search_val=None	pd.DataFrame
Return the main data structure (a Pandas dataframe) - or a part thereof (in which case a column named "search_value" is inserted to the left.) Optionally, limit the dataframe to a specified numbers of rows at the end, or just return row(s) corresponding to a specific search value(s) in the specified column - i.e. the row(s) with the CLOSEST value to the requested one(s). IMPORTANT: if multiple options to restrict the dataset are present, only one is carried out; the priority is: 1) head, 2) tail, 3) filtering, 3) search :param head: (OPTIONAL) Integer. If provided, only show the first several rows; as many as specified by that number. :param tail: (OPTIONAL) Integer. If provided, only show the last several rows; as many as specified by that number. If the "head" argument is passed, this argument will get ignored :param val_start: (OPTIONAL) Perform a FILTERING using the start value in the the specified column - ASSUMING the dataframe is ordered by that value (e.g. a system time) :param val_end: (OPTIONAL) FILTER by end value. Either one or both of start/end values may be provided :param search_col: (OPTIONAL) String with the name of a column in the dataframe, against which to match the value below :param search_val: (OPTIONAL) Number, or list/tuple of numbers, with value(s) to search in the above column :return: A Pandas dataframe, with all or some of the rows that were stored in the main data structure. If a search was requested, insert a column named "search_value" to the left

name

arguments

returns

get_dataframe

self, head=None, tail=None, val_start=None, val_end=None, search_col=None, search_val=None

pd.DataFrame

        Return the main data structure (a Pandas dataframe) 
        - or a part thereof (in which case a column named "search_value" is inserted to the left.)

        Optionally, limit the dataframe to a specified numbers of rows at the end,
        or just return row(s) corresponding to a specific search value(s) in the specified column
        - i.e. the row(s) with the CLOSEST value to the requested one(s).

        IMPORTANT:  if multiple options to restrict the dataset are present, only one is carried out;
                    the priority is:  1) head,  2) tail,  3) filtering,  3) search

        :param head:        (OPTIONAL) Integer.  If provided, only show the first several rows;
                                as many as specified by that number.
        :param tail:        (OPTIONAL) Integer.  If provided, only show the last several rows;
                                as many as specified by that number.
                                If the "head" argument is passed, this argument will get ignored

        :param val_start:  (OPTIONAL) Perform a FILTERING using the start value in the the specified column
                                - ASSUMING the dataframe is ordered by that value (e.g. a system time)
        :param val_end:    (OPTIONAL) FILTER by end value.
                                Either one or both of start/end values may be provided

        :param search_col:  (OPTIONAL) String with the name of a column in the dataframe,
                                against which to match the value below
        :param search_val:  (OPTIONAL) Number, or list/tuple of numbers, with value(s)
                                to search in the above column

        :return:            A Pandas dataframe, with all or some of the rows
                                that were stored in the main data structure.
                                If a search was requested, insert a column named "search_value" to the left

name	arguments	returns
clear_dataframe	self	None
Do a clean start :return: None

name	arguments	returns
set_caption_last_snapshot	self, caption: str	None
Set the caption field of the last (most recent) snapshot to the given value. Any previous value gets over-written :param caption: :return: None

Class MovieArray

    Use this structure if your "snapshots" (data to add to the cumulative collection) are Numpy arrays,
    of any dimension - but always retaining that same dimension.

    Usually, the snapshots will be dump of the entire system state, or parts thereof, but could be anything.
    Typically, each snapshot is taken at a different time (for example, to create a history), but could also
    be the result of varying some parameter(s)

    DATA STRUCTURE:
        A Numpy array of 1 dimension larger than that of the snapshots

        EXAMPLE: if the snapshots are the 1-d numpy arrays [1., 2., 3.] and [10., 20., 30.]
                        then the internal structure will be the matrix
                        [[1., 2., 3.],
                         [10., 20., 30.]]

name	arguments	returns
__init__	self, parameter_name="SYSTEM TIME"
:param parameter_name: A label explaining what the snapshot parameter is. Typically it's "SYSTEM TIME" (default), but could be anything

name	arguments	returns
__len__	self	int
Return the number of snapshots comprising the movie :return: An integer

name	arguments	returns
__str__	self

name	arguments	returns
store	self, par, data_snapshot: np.array, caption = ""	None
Save up the given data snapshot, and its associated parameters and optional caption EXAMPLES: store(par = 8., data_snapshot = np.array([1., 2., 3.]), caption = "State after injection of 2nd reagent") store(par = {"a": 4., "b": 12.3}, data_snapshot = np.array([1., 2., 3.])) :param par: Typically, the System Time - but could be anything that parametrizes the snapshots (e.g., a dictionary, or any desired data structure.) It doesn't have to remain consistent, but it's probably good practice to keep it so :param data_snapshot: A Numpy array, of any shape - but must keep that same shape across snapshots :param caption: OPTIONAL string to describe the snapshot :return: None

name

arguments

returns

store

self, par, data_snapshot: np.array, caption = ""

None

        Save up the given data snapshot, and its associated parameters and optional caption

        EXAMPLES:
                store(par = 8., data_snapshot = np.array([1., 2., 3.]), caption = "State after injection of 2nd reagent")
                store(par = {"a": 4., "b": 12.3}, data_snapshot = np.array([1., 2., 3.]))

        :param par:             Typically, the System Time - but could be anything that parametrizes the snapshots
                                    (e.g., a dictionary, or any desired data structure.)
                                    It doesn't have to remain consistent, but it's probably good practice to keep it so
        :param data_snapshot:   A Numpy array, of any shape - but must keep that same shape across snapshots
        :param caption:         OPTIONAL string to describe the snapshot
        :return:                None

name	arguments	returns
get_array	self	np.array
Return the main data structure - the Numpy Array :return: A Numpy Array with the main data structure

name	arguments	returns
get_parameters	self	list
Return all the parameter values :return: A list with the parameter values

name	arguments	returns
get_captions	self	[str]
Return all the captions :return: A list with the captions

name	arguments	returns
get_shape	self	tuple
:return: A tuple with the shape of the snapshots

Class MovieGeneral

    A "general movie" is a list of snapshots of any values that the user wants to preserve,
    such as the state of the entire system, or of parts thereof,
    either taken at different times,
    or resulting from varying some parameter(s)

    This class accept data in arbitrary formats

    MAIN DATA STRUCTURE:
        A list of triplets.
        Each triplet is of the form (parameter value, caption, snapshot_data)
            1) The "parameter" is typically time, but could be anything.
               (a descriptive meaning of this parameter is stored in the object attribute "parameter_name")
            2) "snapshot_data" can be anything of interest, typically a clone of some data element.
            3) "caption" is just a string with an optional label.

        If the "parameter" is time, it's assumed to be in increasing order

        EXAMPLE:
            [
                (0., DATA_STRUCTURE_1, "Initial state"),
                (8., DATA_STRUCTURE_2, "State immediately after injection of 2nd reagent")
            ]

name	arguments	returns
__init__	self, parameter_name="SYSTEM TIME"
:param parameter_name: A label explaining what the snapshot parameter is. Typically it's "SYSTEM TIME" (default), but could be anything

name	arguments	returns
__len__	self

name	arguments	returns
__str__	self

name	arguments	returns
store	self, par, data_snapshot, caption = ""	None
Save up the given data snapshot EXAMPLE: store(par = 8., data_snapshot = {"c1": 10., "c2": 20.}, caption = "State immediately before injection of 2nd reagent") store(par = {"a": 4., "b": 12.3}, data_snapshot = [999., 111.], caption = "Parameter is a dict; data is a list") IMPORTANT: if passing a variable pointing to an existing mutable structure (such as a list, dict, object) make sure to first clone it, to preserve it as it! :param par: Typically, the System Time - but could be anything that parametrizes the snapshots (e.g., a dictionary, or any desired data structure.) It doesn't have to remain consistent, but it's probably good practice to keep it so :param data_snapshot: Data in any format (such as a Numpy array, or an object) :param caption: OPTIONAL string to describe the snapshot :return: None

name

arguments

returns

store

self, par, data_snapshot, caption = ""

None

        Save up the given data snapshot

        EXAMPLE:
                store(par = 8.,
                      data_snapshot = {"c1": 10., "c2": 20.},
                      caption = "State immediately before injection of 2nd reagent")

                store(par = {"a": 4., "b": 12.3},
                     data_snapshot = [999., 111.],
                     caption = "Parameter is a dict; data is a list")

        IMPORTANT:  if passing a variable pointing to an existing mutable structure (such as a list, dict, object)
                    make sure to first *clone* it, to preserve it as it!

        :param par:             Typically, the System Time - but could be anything that parametrizes the snapshots
                                    (e.g., a dictionary, or any desired data structure.)
                                    It doesn't have to remain consistent, but it's probably good practice to keep it so
        :param data_snapshot:   Data in any format (such as a Numpy array, or an object)
        :param caption:         OPTIONAL string to describe the snapshot
        :return:                None

name	arguments	returns
get_movie	self	list
Return the main data structure - the list of snapshots, with their attributes :return:

name	arguments	returns
get_data	self	list
Return a list of all the snapshots :return: A list of all the snapshots

name	arguments	returns
get_parameters	self	list
Return all the parameter values :return: A list with all the parameter values

name	arguments	returns
get_captions	self	[str]
Return all the captions :return: A list with all the captions