Interop

all_components(stock::Stock) -> Vector{<:StockComponent}
all_components(stocks::Vector{<:Stock}) -> Vector{<:StockComponent}

Like all_reagents, but also includes any Organisms present – gathers every StockComponent (reagent or organism) a Stock (or collection of Stocks) contains. all_reagents itself is unchanged and remains organism-blind; use all_components wherever organisms should participate in the enumeration.

all_reagents(stock::Stock) -> Vector{<:Reagent}
all_reagents(stocks::Vector{<:Stock}) -> Vector{<:Reagent}

Every solid and liquid Reagent present in stock, or in any of stocks, without duplicates. Organisms are not included; use all_components when they should be.

component_df(stocks::Vector{<:Stock}; measure::Function=concentration, kwargs...) -> DataFrame

Like reagent_df, but gathers via all_components instead of all_reagents, so organisms are included as columns alongside reagents (measure – concentration or quantity – already has Organism methods).

component_to_string(r::CHESSCore.Reagent; reagent_context=CHESSCore, kwargs...) -> String
component_to_string(o::CHESSCore.Organism; org_context=CHESSCore, kwargs...) -> String

Convert a CHESSCore.Reagent or CHESSCore.Organism into a stable string identifier.

Returns the registered symbol for the argument (via symbol) when it can be found in reagent_context/org_context — this is useful because a registered component's display name (CHESSCore.name(x)) is not necessarily the same string that reagentparse/orgparse expect to resolve it. If not found (e.g. an ad hoc reagent/organism built on the fly), falls back to CHESSCore.name(x), which is sufficient to reconstruct such components.

See also: string_to_component

concentration(stock::CHESSCore.Stock,ingredient::CHESSCore.Solid)
concentration(stock::CHESSCore.Stock,ingredient::CHESSCore.Liquid)
concentration(stock::CHESSCore.Stock,ingredient::CHESSCore.Organism)

Return the concentration of an ingredient relative to the stock's own total (CHESSCore.quantity(stock)) via _relative_amount — a mass for Mixture, a volume for Solution/Culture. This is what the "vc" dataframe format needs: percent when the ingredient shares the total's physical dimension (e.g. a liquid within a Solution's volume total, or a solid within a Mixture's mass total), an amount-per-unit-of-total ratio otherwise (e.g. a solid's mass within a Solution's volume total, in g/mL). Not volume_estimate – that's a different, only-partially-defined physical-volume estimate used elsewhere (Well.jl capacity checks, pH), not the right denominator for a relative concentration.

For an Organism, Biomass's dimension (OD*Volume) never matches the volume total's, so this always takes the cross-dimension branch and returns a plain Biomass/total ratio in OD – i.e. the culture's current, on-demand-derived optical density, never a stored value.

quantity(stock::CHESSCore.Stock,ingredient::CHESSCore.Solid)
quantity(stock::CHESSCore.Stock,ingredient::CHESSCore.Liquid)
quantity(stock::CHESSCore.Stock,ingredient::CHESSCore.Organism)

Return the quantity of an ingredient in a stock using the preferred units for that ingredient (an organism's Biomass in OD*mL).

reagent_df(stocks::Vector{<:Stock}; measure::Function=concentration, kwargs...) -> DataFrame

Tabulate stocks with one row per stock and one column per reagent found by all_reagents. Each cell is measure(stock, reagent): concentration by default, or pass measure=quantity for absolute amounts. Column names come from component_to_string, which receives kwargs. Organisms are left out; use component_df to include them.

string_to_component(str::AbstractString, chem_type::Type{<:Reagent};
                    reagent_context=CHESSCore, kwargs...) -> Reagent
string_to_component(str::AbstractString, ::Type{Organism};
                    org_context=CHESSCore, kwargs...) -> Organism

Convert a string into a Reagent or Organism instance.

The Reagent method first attempts to parse str using CHESSCore.reagentparse, which may return a registered reagent object from reagent_context. If parsing fails, it emits a warning and falls back to constructing a new reagent of type chem_type using str as the identifier/name and missing for unknown properties.

The Organism method first attempts CHESSCore.orgparse (org_context); if that fails, it emits a warning and falls back to splitting str into "genus species strain" form – errors if str doesn't have exactly three space-separated parts, since (unlike Reagent) Organism has no missing-tolerant fields to build a permissive fallback from a single unstructured string.

Arguments

• str::AbstractString: The reagent/organism identifier to parse (e.g., a registered name, alias, or other parseable representation).
• chem_type::Type{<:Reagent}: Concrete Reagent subtype to instantiate if str is not registered / cannot be parsed.

Keyword Arguments

• reagent_context=CHESSCore: Module or list of modules to search for registered reagents during parsing (forwarded to reagentparse).
• org_context=CHESSCore: Module or list of modules to search for registered organisms during parsing (forwarded to orgparse).

Returns

• A Reagent object. If reagentparse succeeds, the parsed/registered object is returned; otherwise, a new chem_type(str, missing, missing, missing) is returned.
• An Organism object. If orgparse succeeds, the parsed/registered object is returned; otherwise, str is split into Organism(genus, species, strain).

Notes

The Reagent method is intentionally permissive: unknown reagents do not error, but are treated as reagents with unspecified properties (missing), which may affect downstream calculations that require those properties. The Organism method is not – an unregistered, malformed organism string errors rather than guessing.

See also: component_to_string

string_to_component(str::AbstractString, unit::Unitful.Units;
                    reagent_context=CHESSCore, org_context=CHESSCore, kwargs...) -> StockComponent

Infer a StockComponent from str and the dimension of unit – used by the "vc"/"q" DataFrame format, where a column's identity has to be guessed from its unit when it isn't otherwise registered. Tries reagentparse(str) first; on failure, dispatches on unit's dimension: a bare OD dimension (vc's organism "concentration") or a Biomass dimension (OD*Volume, q's organism quantity) both delegate to string_to_component(str,::Type{Organism}); mass/molarity/ density/amount dimensions assume an unregistered Solid; dimensionless/volume dimensions assume an unregistered Liquid.

add_stock!(lw::Labware, stock::Stock, row::Integer, col::Integer) -> Labware

Deposit stock into the well at (row, col) in lw. A convenience wrapper around deposit! for manually filling labware by grid position. If the selected well is not empty, a warning is emitted and the deposit is still attempted.

df_to_labware(df::DataFrame, units::DataFrame; kwargs...) -> Vector{Labware}

Reconstruct labware (and deposited well contents) from a dataframe representation.

df_to_labware expects labware metadata (labware, name, and well) plus the stock columns needed to reconstruct well contents. Stock content may be encoded in any stock dataframe format supported by df_to_stock.

Required columns in df

df must include the following columns:

• labware: LocationKind name registered in location_kinds (e.g. "WP96"), used to look up the kind and call build_location. Valid codes are keys(location_kinds).
• name: Name/identifier of the labware instance. Multiple rows may share the same name (and labware) to indicate multiple wells on the same physical item.
• well: Well identifier in row/column form (e.g. "A1", "H2", "B12")

All remaining columns are treated as stock data and are passed to df_to_stock.

Behavior

• Creates one labware instance per unique (labware, name) pair, via build_location(location_kinds[Symbol(labware)], name) – these are uncommitted (no database connection needed, location_id is nothing); commit the result yourself (e.g. via commit_location! in CHESSDatabase) if you want it tracked.
• Parses a Stock per row from the stock columns using df_to_stock.
• Looks up each row's well by name (lw[well]), not by position.

Arguments

• df::DataFrame: Labware + stock data (one row per filled well).
• units::DataFrame: Units/metadata table for the stock columns (passed through to df_to_stock).

See also

labware_to_df, df_to_stock

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

labware_to_df(lw::Labware, format::AbstractString = "vc"; kwargs...) -> (DataFrame, DataFrame)

Convenience method for exporting a single Labware object. Equivalent to labware_to_df([lw], format; kwargs...).

See also: labware_to_df(::Vector{<:Labware})

labware_to_df(lws::Vector{<:Labware}, format::AbstractString = "vc"; kwargs...) -> (DataFrame, DataFrame)

Convert labware into a dataframe representation suitable for serialization

The output contains one row per non-empty well and includes three labware descriptor columns plus the stock columns:

• labware: string(kind(lw).name) – the registered LocationKind name for the labware containing the well (not typeof(lw); every Labware shares one concrete type, so the model/kind lives in kind(lw), not the Julia type).
• name: CHESSCore.name(lw) labware instance name
• well: CHESSCore.name(w) well identifier (e.g., "A1")

Stock content is converted using stock_to_df in the requested format. The returned units dataframe corresponds to the stock columns (not the labware/name/well columns).

Arguments

• lws::Vector{<:Labware}: Labware objects to export.
• format::AbstractString = "vc": Stock encoding passed to stock_to_df.

See also

df_to_labware, stock_to_df

q_to_stock(quant::DataFrame, units::DataFrame; kwargs...) -> Vector{Stock}

Build one Stock per row of a table in the quantity ("q") format: one column per reagent or organism holding an absolute amount (mass, volume, moles, or biomass). units works as in vc_to_stock, and so do the reagent_context/org_context keywords. Throws an error if units holds concentration units (use vc_to_stock).

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

stock_to_q(stocks::Vector{<:Stock}; kwargs...) -> (DataFrame, DataFrame)

Inverse of q_to_stock: write stocks as a quantity table and a matching units table, with each component's absolute quantity in its own column. kwargs are passed to component_to_string.

stock_to_vc(stocks::Vector{<:Stock}; kwargs...) -> (DataFrame, DataFrame)

Inverse of vc_to_stock: write stocks as a volume/concentration table and a matching units table. Each stock's total quantity goes in the "volume" column, and each component's concentration in its own column. kwargs are passed to component_to_string.

stocks(lw::Labware) -> Vector{Stock}
stocks(lws::Vector{<:Labware}) -> Vector{Stock}

Collect the Stock held in every well of lw (or every well of every labware in lws), in well order.

vc_to_stock(vc::DataFrame, units::DataFrame; kwargs...) -> Vector{Stock}

Build one Stock per row of a table in the volume/concentration ("vc") format: a "volume" column for each stock's total, plus one concentration column per reagent or organism. units gives the unit string for every column, either in one row shared by all stocks or one row per stock. Column names are parsed with string_to_component, which takes the reagent_context and org_context keywords. Throws an error if units holds quantity units (use q_to_stock) or a concentration unit that does not combine with the volume.

See the Interop manual page for the table formats. df_to_stock picks the format automatically.

attribute_to_dict(a::Attribute) -> Dict{String,Any}

"state" is "value"/"missing"/"unknown" (mirrors isunknown/ismissing), with "value" holding the actual number only when "state" == "value" – kept as a separate field (rather than a sentinel string in "value" itself) so a real value can never collide with the sentinels.

See also: dict_to_attribute

dict_to_attribute(d::Dict) -> Attribute

Inverse of attribute_to_dict.

dict_to_location(d::Dict; reagent_context=CHESSCore, org_context=CHESSCore, kwargs...) -> Location

Inverse of location_to_dict. Reconstructs an uncommitted Location (location_id === nothing, via build_location) and, recursively, its subtree. The "kind" name is resolved against the live location_kinds registry – for a capability-bearing location, this means "actuatable_attributes"/"performable_operations"/"readable_types" in d are informational only and never consulted; the reconstructed location's real capabilities always come from its resolved LocationKind, exactly like "vendor"/"catalog" for a Labware.

dict_to_read(d::Dict) -> Read

Inverse of read_to_dict.

dict_to_stock(d::Dict; reagent_context=CHESSCore, org_context=CHESSCore, kwargs...) -> Stock

Inverse of stock_to_dict.

location_to_dict(x::Location) -> Dict{String,Any}

Convert x (and, recursively, its subtree) to a plain, JSON-safe Dict. Common to every subtype: "kind" (registered LocationKind name), "name", "is_locked", "is_active", "attributes" (own attributes only, not the derived/inherited environment – keyed by attribute name, each an attribute_to_dict result), and "reads" (a Vector of read_to_dict results). location_id/parent are omitted – see the module-level comment.

Per-subtype: GenericLocation adds "children" (nested location_to_dict results, recursive). Any capability-bearing location (is_capable, GenericLocation or Labware alike) also adds informational (non-authoritative – see dict_to_location) "actuatable_attributes"/"performable_operations"/"readable_types". Well adds "cost" and "stock" (stock_to_dict). Labware adds "wells" – a shape[1]-row, shape[2]-column nested array of per-slot Well dicts, in the same (row,col) order as children(x) – plus informational "vendor"/"catalog". This is the one non-flat exception: a Labware and its wells round-trip as a single unit, matching how a human actually thinks about a plate when planning an experiment.

Accepts reagent_context/org_context keywords (forwarded to stock_to_dict for any Well, nested arbitrarily deep) so a Well's contents resolve to their registered reagent/organism names rather than falling back to ad hoc display names – pass whatever context you'd pass to rgt"..."/ org"..." lookups (e.g. reagent_context=[CHESSCore,MyLabModule]) if reagents/organisms are registered outside plain CHESSCore.

See also: dict_to_location

read_to_dict(r::Read) -> Dict{String,Any}

Mirrors attribute_to_dict's "state"/"value" split; "unit" is nothing for a qualitative ReadKind, and "time" is an ISO-8601 string (or nothing).

See also: dict_to_read

stock_to_dict(s::Stock; reagent_context=CHESSCore, org_context=CHESSCore, kwargs...) -> Dict{String,Any}

Convert s to a plain, JSON-safe Dict – a quantity-based (exact, unambiguous) encoding, mirroring the "q" DataFrame format (stock_to_q) rather than "vc"'s relative-concentration form. Reusable standalone or nested inside a Well's location_to_dict output.

See also: dict_to_stock

registry_summary(context=vcat([CHESSCore],CHESSCore.labmodules))

Assemble every registered constant across context (a Module or list of Modules, default: CHESSCore plus every module registered via register_lab) into one NamedTuple, keyed by category: reagents, species, organisms, locations, attributes, reads, stocks.

organisms/locations/attributes/reads are read directly from CHESSCore's central registries (orgprops/location_kinds/attribute_kinds/read_kinds), which already hold everything needed. reagents/species have no such registry, and stocks' registry (stock_recipes) only reflects Stocks explicitly registered via @stock – so like symbol's own reverse lookup, all three are instead found here by scanning names(m; all=true) of each module in context and filtering by type. This deliberately finds every Stock in scope for a complete summary, including ones never registered via @stock – unlike @stock_str's intentionally registry-only lookup.

This is a pure data-assembly step, intended as the groundwork for documentation generation (e.g. a script that renders the result to Markdown/HTML) – it does not itself produce any rendered output.