Stocks

Creating Stocks from Tables

Pourfecto represents source and target materials as JLIMS.Stock objects. In most workflows, users do not need to construct Stocks manually. Instead, stocks can be created from tabular data using df_to_stock.

This is useful when reading stocks from CSV files, spreadsheets, notebooks, or user-facing forms.

The main stock conversion functions are:

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

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

A stock table is represented by two DataFrames:

1. df: the main stock data
2. 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:

The parser df_to_stock automatically detects which format is being used.

If both df and units contain a "volume" column, Pourfecto treats the table as a volume/concentration table.

Otherwise, Pourfecto treats the table as a quantity table.

Volume/concentration format

The volume/concentration format is useful when each row represents a stock with a total volume and one or more reagent concentrations.

Conceptually:

with a corresponding units table:

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)

Because both tables contain a "volume" column, Pourfecto parses this as a "vc" table.

Quantity format

The quantity format is useful when each row represents a stock directly by the amount of each reagent it contains.

Conceptually:

with a corresponding units table:

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)

Because these tables do not contain a "volume" column, Pourfecto parses this as a "q" table.

Automatic reagent creation

When parsing stock tables, reagent names are usually taken from the column names.

Pourfecto can turn those reagent names into JLIMS.Chemical objects automatically. Registered JLIMS chemicals are used when available. Unknown reagents are created on the fly with missing chemical properties.

For example, a column named:

:sodium_chloride

or

:dye

can be interpreted as a reagent name.

If the reagent is not registered, Pourfecto will warn and create a generic chemical object.

See also: string_to_reagent, reagent_to_string

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 manually with convenient arithmetic syntax from JLIMS.

This is useful in notebooks, tests, examples, and small workflows where writing a dataframe would be unnecessary.

JLIMS overloads the * operator so that quantities and chemicals can be combined directly:

using JLIMS
using Pourfecto 
using Unitful

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

10u"mg" * sodium_chloride
1u"mL" * water 

Depending on the chemical type and unit, these expressions create solid stocks Mixtures or liquid stocks Solutions

In general:

• mass * Solid creates a Mixture
• amount * Solid creates a Mixture
• volume * Liquid creates a Solution

Combining stocks

Stocks can be combined using +.

For example:

stock = 900u"µL" * chem"water" + 100u"µL" * chem"ethanol" # assumes "water" and "ethanol" are pre-registered chemicals 

This creates a stock containing both water and ethanol.

A more complex example might include both solids and liquids:

buffer = 1u"mL" * chem"water" + 10u"mg" * chem"sodium_chloride" # assumes "water" and "sodium_chloride" are pre-registered chemicals 

Scaling stocks

Stocks can be multiplied by scalar values.

stock2 = 2 * stock

This returns a new stock with all chemical quantities scaled by the given factor.

Scalar multiplication works in either order:

stock2 = 2 * stock
stock3 = stock * 2

Stocks can also be divided by scalars:

half_stock = stock / 2

Rescaling a stock to a target quantity

A stock can be scaled to a target total quantity using:

target_quantity * stock

For example, if stock represents a liquid mixture, you can scale it to a final volume:

small_stock = 100u"µL" * stock

or:

large_stock = 10u"mL" * stock

Example: Adding multiple chemicals in a For Loop

using JLIMS
using Unitful

chem_names = ["A","B","C","D"]
chem_masses = [1,2,3,4]

stock = 1u"mL" * string_to_reagent("water",Liquid) 
for i in eachindex(chem_names)
    stock += (chem_masses[i] *u"mg") * string_to_reagent(chem_names[i],Solid) 
end 

This creates a stock containing:

• 1 mL water
• 1 mg A
• 2 mg B
• 3 mg C
• 4 mg D

Operator summary