Stocks

Note

This page describes how Pourfecto converts tables to and from CHESSCore's Stock type. It assumes familiarity with Stock, which CHESSCore's Stocks page describes.

Creating Stocks from Tables

Pourfecto represents source and target materials as CHESSCore Stock objects. Most workflows create them from tabular data with df_to_stock instead of constructing them by hand. This suits stocks read from CSV files, spreadsheets, notebooks, or forms.

The main stock conversion functions are:

CHESSCore.df_to_stock — Function

df_to_stock(df::DataFrame, units::DataFrame; kwargs...) -> Vector{Stock}

Parse a pair of DataFrame representations into a vector of Stocks.

This is a format-dispatching wrapper that supports two encodings:

"vc" (volume/concentration): tables include a "volume" column (in both df and units) and are parsed via vc_to_stock(df, units; kwargs...).
"q" (quantity): tables omit "volume" and are parsed via q_to_stock(df, units; kwargs...).

The function auto-detects the encoding by checking for the presence of the "volume" column in both df and units.

Arguments

df::DataFrame: Main stock table (one row per stock; columns depend on the chosen format).
units::DataFrame: Units/metadata table aligned with df (e.g., unit strings for numeric columns).

See also

stock_to_df

source

CHESSCore.stock_to_df — Function

stock_to_df(stocks::Vector{<:CHESSCore.Stock}, format::AbstractString = "vc"; kwargs...) -> (DataFrame, DataFrame)

Convert a vector of Stocks into a pair of dataframes (df, units) suitable for serialization.

Two formats are supported:

format = "vc": volume/concentration representation (stock_to_vc).
format = "q": quantity representation (stock_to_q).

Arguments

stocks::Vector{<:CHESSCore.Stock}: Stocks to convert.
format::AbstractString = "vc": Output encoding; must be one of ["q", "vc"].

See also

df_to_stock

source

A stock table is represented by two DataFrames:

df: the main stock data
units: the units associated with the values in df

stocks = df_to_stock(df, units)

The reverse operation is:

df, units = stock_to_df(stocks)

Supported stock table formats

Pourfecto supports two stock table encodings:

Format	Description
`"vc"`	Volume/Concentration format
`"q"`	Quantity format

df_to_stock detects the format. If both df and units contain a "volume" column, the table is a volume/concentration table. Otherwise it is a quantity table.

Volume/concentration format

In the volume/concentration format, each row is a stock with a total volume and one or more reagent concentrations. For example:

volume	reagent_a	reagent_b
1000	10	5
500	20	0

with a corresponding units table:

volume	reagent_a	reagent_b
µL	mM	mM

Example:

using DataFrames
using Unitful
using Pourfecto

df = DataFrame(
    volume = [1000, 500],
    sodium_chloride = [10, 20],
    dye = [5, 0],
)

units = DataFrame(
    volume = ["µL"],
    sodium_chloride = ["mM"],
    dye = ["mM"],
)

stocks = df_to_stock(df, units)

Both tables contain a "volume" column, so this is parsed as a "vc" table.

Warning

A reagent cannot be named "volume", because the parser reads that name as the total volume.

Quantity format

In the quantity format, each row is a stock given directly by the amount of each reagent it contains. For example:

water	sodium_chloride
1000	10
500	5

with a corresponding units table:

water	sodium_chloride
µL	mg

Example:

using DataFrames
using Pourfecto

df = DataFrame(
    water = [1000, 500],
    sodium_chloride = [10, 5],
)

units = DataFrame(
    water = ["µL"],
    sodium_chloride = ["mg"],
)

stocks = df_to_stock(df, units)

These tables have no "volume" column, so this is parsed as a "q" table.

Reagent names

Reagent names come from the column names. Pourfecto converts each name to a Reagent with string_to_component. A registered reagent is used when one exists. Otherwise a generic chemical is created with unknown properties, and a warning is shown. In the examples above, the columns sodium_chloride and dye are read as reagent names.

Note

A reagent that is not registered can be used for planning and scheduling. Calculations that need molecular weight or density require a registered reagent.

Converting stocks back to dataframes

Use stock_to_df to export stocks back into tabular form.

df, units = stock_to_df(stocks)

By default, this uses the "vc" format:

df, units = stock_to_df(stocks, "vc")

To request quantity format:

df, units = stock_to_df(stocks, "q")

Creating Stocks Manually

Stocks can also be created with CHESSCore's arithmetic. Multiplying a quantity by a reagent builds a stock, adding stocks combines them, multiplying or dividing by a number scales a stock, and multiplying by a quantity rescales it to that total. This suits notebooks, tests, examples, and small workflows where a dataframe is unnecessary:

using Pourfecto, CHESSCore, Unitful

water = string_to_component("water", Liquid)
sodium_chloride = string_to_component("sodium_chloride", Solid)

buffer = 1u"mL" * water + 10u"mg" * sodium_chloride
scaled = 2 * buffer

CHESSCore's Stocks page describes the operations in full.