wellmap.load

wellmap.load(toml_path, *, data_loader=None, merge_cols=None, path_guess=None, path_required=False, on_alert=None, meta=False, extras=False, report_dependencies=False)

Load a microplate layout from a TOML file.

Parse the given TOML file and return a pandas.DataFrame with a row for each well and a column for each experimental condition specified in that file. If the data_loader and merge_cols arguments are provided (which is the most typical use-case), that data frame will also contain columns for any data associated with each well.

Parameters:

• toml_path (str,pathlib.Path) – The path to a file describing the layout of one or more plates. See the File format page for details about this file.

• data_loader (callable) – Indicates that load() should attempt to load the actual data associated with the plate layout, in addition to loading the layout itself. The argument should be a function that takes a pathlib.Path to a data file, parses it, and returns a pandas.DataFrame containing the parsed data. The function may also take an argument named “extras”, in which case the extras return value (described below) will be provided. Note that specifying a data loader implies that path_required is True.

• merge_cols (bool,dict) –

  Indicates whether or not—and if so, how—load() should merge the data frames representing the plate layout and the actual data (provided by data_loader). The argument can either be a boolean or a dictionary:

  If False (or falsey, e.g. None, {}, etc.), the data frames will be returned separately and not be merged. This is the default behavior.

  If True, the data frames will be merged using any columns that share the same name. For example, the layout will always have a column named well, so if the actual data also has a column named well, the merge would happen on those columns.

  If a dictionary, the data frames will be merged using the columns identified in each key-value pair of the dictionary. The keys should be column names from the data frame representing the plate layout (described below; see the layout return value), and the values should be column names from the data frame returned by data_loader. Below are some examples of this argument:

  • {'well0': 'Well'}: Indicates that the “Well” column in the data contains zero-padded well names, like “A01”, “A02”, etc.

  • {'row_i': 'Row', 'col_j': 'Col'}: Indicates that the ‘Row’ and ‘Col’ columns in the data contain 0-indexed coordinates (e.g. 0, 1, 2, …) identifying each row and column, respectively.

  Some details and caveats:

  • In order to successfully merge two columns, the values in those columns must correspond exactly. For example, a column that contains unpadded well names like “A1” cannot be merged with a column that contains padded well names like “A01”. This is why the layout data frame contains so many redundant columns: to increase the chance that one will correspond exactly with a column provided by the data. In some cases, though, it may be necessary for the data_loader function to construct an appropriate merge column.

  • The data frame returned by data_loader() must be tidy. Briefly, a data frame is tidy if each of its columns represents a single variable (e.g. time, fluorescence) and each of its rows represents a single observation.

  • The path column of the layout is automatically included in the merge and never has to be specified (although it is not an error to do so). The reason for this special-case is that load() itself knows what path each data frame was loaded from.

• path_guess (str) – Where to look for a data file if none is specified in the given TOML file. In other words, this is the default value for meta.path. This path is interpreted relative to the TOML file itself (unless it’s an absolute path) and is formatted with a pathlib.Path representing said TOML file. In code, that would be: path_guess.format(Path(toml_path)). A typical value would be something like '{0.stem}.csv'.

• path_required (bool) – Indicates whether or not the given TOML file must reference one or more data files. A ValueError will be raised if this condition is not met. Data files found via path_guess are acceptable for this purpose.

• meta (bool) – If true, return a Meta object containing miscellaneous information that was read from the TOML file but not part of the layout. This includes (i) a dictionary with all the key/values pairs present in the TOML file but not part of the layout, (ii) a set of all the TOML files that were read in the process of loading the layout from the given toml_path, (iii) and a Style object describing how to plot the layout itself.

• extras (bool) – Deprecated.

• report_dependencies (bool) – Deprecated.

• on_alert (callable) – A callback to invoke if the given TOML file contains a warning for the user. The default behavior is to print the warning to the terminal via stderr. If a callback is provided, it must take two arguments: a pathlib.Path to the TOML file containing the alert, and the message itself. Note that this could be called more than once, e.g. if there are included or concatenated files.

Returns:

If neither data_loader nor merge_cols were provided:

• layout (pandas.DataFrame) – Information about the plate layout parsed from the given TOML file. The data frame will have a row for each well and a column for each experimental condition. In addition, there will be several columns identifying each well:

  • plate: The name of the plate for this well. This column will not be present if there are no [plate] blocks in the TOML file.

  • path: The path to the data file associated with the plate for this well. This column will not be present if no data files were referenced by the TOML file.

  • well: The name of the well, e.g. “A1”.

  • well0: The zero-padded name of the well, e.g. “A01”.

  • row: The name of the row for this well, e.g. “A”.

  • col: The name of the column for this well, e.g. “1”.

  • row_i: The row-index of this well, counting from 0.

  • col_j: The column-index of this well, counting from 0.

If data_loader was provided but merge_cols was not:

• layout (pandas.DataFrame) – See above.

• data (pandas.DataFrame) – The concatenated result of calling data_loader() on every path specified in the given TOML file. See pandas.concat() for more information on how the data from different paths are concatenated.

If data_loader and merge_cols were both provided:

• merged (pandas.DataFrame) – The result of merging the layout and data data frames along the columns specified by merge_cols. See pandas.merge() for more details on the merge itself. The resulting data frame will have one or more rows for each well (more are possible if there are multiple data points per well, e.g. a time course), a column for each experimental condition described in the TOML file, and a column for each kind of data loaded from the data files.

If meta was requested:

• meta (Meta) – As described above.