s3-method-dispatch
Summary
Use S3 method dispatch to dynamically route data-frame processing logic based on metadata class attributes, enabling flexible annotation and transformation pipelines that adapt to heterogeneous metabolomics data structures. This skill ensures that generic operations like KEGG_gather select the correct class-specific implementation (e.g., plate_omelette) without explicit conditional branching.
When to use
Your metabolomics data frame has inherited or assigned class metadata (e.g., KEGG hierarchy class determined by assign_hierarchy) and you need to apply a generic operation—such as functional orthology retrieval or data formatting—that must behave differently depending on which classification system (KEGG, KO_Number, Prokaryote, or Eukaryote) is already present. Use this skill when a single function name should produce different outputs for different data structures without forcing the caller to specify the variant.
When NOT to use
- Input data frame has no class attribute or metadata; dispatch will fail or fall back to default method, potentially losing desired logic.
- You need conditional branching based on user input or parameter values rather than object class; use explicit if/else instead of S3 dispatch.
- The operation should behave identically regardless of metabolite classification system; a single function is simpler and avoids dispatch overhead.
Inputs
- metabolomics count data frame with assigned class attribute (output from assign_hierarchy)
- hierarchical metadata columns (KEGG ID, KO number, or prokaryote/eukaryote classifier)
Outputs
- augmented data frame with class-specific formatting applied
- functional orthology and gene annotation columns (for KEGG_gather dispatch)
- formatted output structure appropriate to the dispatched class method
How to apply
Define a generic S3 function (e.g., KEGG_gather or plate_omelette) with a default method and one or more class-specific methods. Ensure the input data frame has been assigned an appropriate class attribute via assign_hierarchy or similar prior setup. When the generic function is called on the data frame, R's method dispatch system automatically selects the matching class method. For KEGG_gather, this means the dispatcher routes to the correct keggGet invocation and parsing path; for plate_omelette, the dispatcher selects the output formatting appropriate to the current class. Verify dispatch by checking the class attribute (e.g., class(data_frame)) before calling the generic function.
Related tools
- KEGGREST (dispatched to retrieve functional orthology and gene names from the KEGG API via keggGet; called within class-specific KEGG_gather method)
- assign_hierarchy (assigns class attributes to the input data frame before dispatch; determines which S3 method will be selected) — https://github.com/connor-reid-tiffany/Omu
- make_omelette (internal parsing and cleaning function called by the dispatched KEGG_gather method to extract KO identifiers and gene names) — https://github.com/connor-reid-tiffany/Omu
- plate_omelette (S3 method dispatched to format cleaned KEGG data into the structure appropriate to the data frame's class) — https://github.com/connor-reid-tiffany/Omu
Examples
KEGG_gather(metabolite_df) # dispatch selects the appropriate method based on class(metabolite_df), e.g., KEGG_gather.KEGG or KEGG_gather.KO_Number
Evaluation signals
- Verify that class(data_frame) returns the expected class name (e.g., 'KEGG', 'KO_Number', 'Prokaryote', or 'Eukaryote') before calling the generic function.
- Check that the correct class-specific method was invoked by inspecting the function signature in the call stack or by adding a debug message to each method.
- Confirm that output columns (e.g., KO numbers and gene names from KEGG_gather) match the formatting and structure expected for that class.
- Verify that no errors or 'no applicable method' warnings are raised; if dispatch fails, the default method will execute, which may not provide the desired result.
- Compare the returned data frame structure to the output specification for the specific class method that should have been dispatched.
Limitations
- S3 dispatch is single-dispatch (based on the class of the first argument only); if you need to dispatch on multiple object types, use S4 or R6 instead.
- If the input data frame loses its class attribute (e.g., via subsetting or transformation), dispatch will revert to the default method, potentially producing incorrect results.
- Method dispatch depends on exact class name matching; typos or class name mismatches will silently fall back to the default method rather than raising an error.
- No changelog is available for the Omu package, so version-specific behavior changes in S3 method implementations are not documented.
Evidence
- [other] Call KEGG_gather on the data frame, which dispatches based on the S3 class determined by existing metadata columns.: "Call KEGG_gather on the data frame, which dispatches based on the S3 class determined by existing metadata columns."
- [other] To assign hierarchical class data, use the assign_hierarchy function and pick the correct identifier, either "KEGG", "KO_Number", "Prokaryote", or "Eukaryote": "To assign hierarchical class data, use the
assign_hierarchy function and pick the correct identifier, either "KEGG", "KO_Number", "Prokaryote", or "Eukaryote""
- [other] Format the cleaned data using the plate_omelette S3 method appropriate to the data frame class.: "Format the cleaned data using the plate_omelette S3 method appropriate to the data frame class."
- [other] The KEGG_gather S3 method retrieves data from the KEGG API using the keggGet function from the KEGGREST package to obtain functional orthology and gene names for metabolite-annotated data frames.: "The KEGG_gather S3 method retrieves data from the KEGG API using the keggGet function from the KEGGREST package to obtain functional orthology and gene names for metabolite-annotated data frames."
- [other] To gather functional orthology and gene data, Omu uses an S3 method called KEGG_gather, which retrieves data from the KEGG API: "To gather functional orthology and gene data, Omu uses an S3 method called
KEGG_gather, which retrieves data from the KEGG API"
1---2name: s3-method-dispatch3description: Use when your metabolomics data frame has inherited or assigned class metadata (e.4license: CC-BY-4.05---67# s3-method-dispatch89## Summary1011Use S3 method dispatch to dynamically route data-frame processing logic based on metadata class attributes, enabling flexible annotation and transformation pipelines that adapt to heterogeneous metabolomics data structures. This skill ensures that generic operations like KEGG_gather select the correct class-specific implementation (e.g., plate_omelette) without explicit conditional branching.1213## When to use1415Your metabolomics data frame has inherited or assigned class metadata (e.g., KEGG hierarchy class determined by assign_hierarchy) and you need to apply a generic operation—such as functional orthology retrieval or data formatting—that must behave differently depending on which classification system (KEGG, KO_Number, Prokaryote, or Eukaryote) is already present. Use this skill when a single function name should produce different outputs for different data structures without forcing the caller to specify the variant.1617## When NOT to use1819- Input data frame has no class attribute or metadata; dispatch will fail or fall back to default method, potentially losing desired logic.20- You need conditional branching based on user input or parameter values rather than object class; use explicit if/else instead of S3 dispatch.21- The operation should behave identically regardless of metabolite classification system; a single function is simpler and avoids dispatch overhead.2223## Inputs2425- metabolomics count data frame with assigned class attribute (output from assign_hierarchy)26- hierarchical metadata columns (KEGG ID, KO number, or prokaryote/eukaryote classifier)2728## Outputs2930- augmented data frame with class-specific formatting applied31- functional orthology and gene annotation columns (for KEGG_gather dispatch)32- formatted output structure appropriate to the dispatched class method3334## How to apply3536Define a generic S3 function (e.g., KEGG_gather or plate_omelette) with a default method and one or more class-specific methods. Ensure the input data frame has been assigned an appropriate class attribute via assign_hierarchy or similar prior setup. When the generic function is called on the data frame, R's method dispatch system automatically selects the matching class method. For KEGG_gather, this means the dispatcher routes to the correct keggGet invocation and parsing path; for plate_omelette, the dispatcher selects the output formatting appropriate to the current class. Verify dispatch by checking the class attribute (e.g., class(data_frame)) before calling the generic function.3738## Related tools3940- **KEGGREST** (dispatched to retrieve functional orthology and gene names from the KEGG API via keggGet; called within class-specific KEGG_gather method)41- **assign_hierarchy** (assigns class attributes to the input data frame before dispatch; determines which S3 method will be selected) — https://github.com/connor-reid-tiffany/Omu42- **make_omelette** (internal parsing and cleaning function called by the dispatched KEGG_gather method to extract KO identifiers and gene names) — https://github.com/connor-reid-tiffany/Omu43- **plate_omelette** (S3 method dispatched to format cleaned KEGG data into the structure appropriate to the data frame's class) — https://github.com/connor-reid-tiffany/Omu4445## Examples4647```48KEGG_gather(metabolite_df) # dispatch selects the appropriate method based on class(metabolite_df), e.g., KEGG_gather.KEGG or KEGG_gather.KO_Number49```5051## Evaluation signals5253- Verify that class(data_frame) returns the expected class name (e.g., 'KEGG', 'KO_Number', 'Prokaryote', or 'Eukaryote') before calling the generic function.54- Check that the correct class-specific method was invoked by inspecting the function signature in the call stack or by adding a debug message to each method.55- Confirm that output columns (e.g., KO numbers and gene names from KEGG_gather) match the formatting and structure expected for that class.56- Verify that no errors or 'no applicable method' warnings are raised; if dispatch fails, the default method will execute, which may not provide the desired result.57- Compare the returned data frame structure to the output specification for the specific class method that should have been dispatched.5859## Limitations6061- S3 dispatch is single-dispatch (based on the class of the first argument only); if you need to dispatch on multiple object types, use S4 or R6 instead.62- If the input data frame loses its class attribute (e.g., via subsetting or transformation), dispatch will revert to the default method, potentially producing incorrect results.63- Method dispatch depends on exact class name matching; typos or class name mismatches will silently fall back to the default method rather than raising an error.64- No changelog is available for the Omu package, so version-specific behavior changes in S3 method implementations are not documented.6566## Evidence6768- [other] Call KEGG_gather on the data frame, which dispatches based on the S3 class determined by existing metadata columns.: "Call KEGG_gather on the data frame, which dispatches based on the S3 class determined by existing metadata columns."69- [other] To assign hierarchical class data, use the assign_hierarchy function and pick the correct identifier, either "KEGG", "KO_Number", "Prokaryote", or "Eukaryote": "To assign hierarchical class data, use the ```assign_hierarchy``` function and pick the correct identifier, either "KEGG", "KO_Number", "Prokaryote", or "Eukaryote""70- [other] Format the cleaned data using the plate_omelette S3 method appropriate to the data frame class.: "Format the cleaned data using the plate_omelette S3 method appropriate to the data frame class."71- [other] The KEGG_gather S3 method retrieves data from the KEGG API using the keggGet function from the KEGGREST package to obtain functional orthology and gene names for metabolite-annotated data frames.: "The KEGG_gather S3 method retrieves data from the KEGG API using the keggGet function from the KEGGREST package to obtain functional orthology and gene names for metabolite-annotated data frames."72- [other] To gather functional orthology and gene data, Omu uses an S3 method called KEGG_gather, which retrieves data from the KEGG API: "To gather functional orthology and gene data, Omu uses an S3 method called ```KEGG_gather```, which retrieves data from the KEGG API"
HolobiomicsLab