Adapter

auto_detect_tool(external_files)

Auto-detect the external tool based on file patterns.

Parameters:

Name	Type	Description	Default
external_files	List[str]	List of external tool output file paths	required

Returns:

Type	Description
ExternalTool	ExternalTool enum value based on detected patterns

Source code in src/rnapolis/adapter.py

def auto_detect_tool(external_files: List[str]) -> ExternalTool:
    """
    Auto-detect the external tool based on file patterns.

    Args:
        external_files: List of external tool output file paths

    Returns:
        ExternalTool enum value based on detected patterns
    """
    if not external_files:
        return ExternalTool.MAXIT

    for file_path in external_files:
        basename = os.path.basename(file_path)

        # Check for FR3D pattern
        if basename.endswith("basepair_detail.txt"):
            return ExternalTool.FR3D

        # Check for RNAView pattern
        if basename.endswith(".out"):
            return ExternalTool.RNAVIEW

        # Check for BPNet pattern
        if basename.endswith("basepair.json"):
            return ExternalTool.BPNET

        # Check for MC-Annotate pattern
        if basename.endswith("stdout.txt"):
            return ExternalTool.MCANNOTATE

        # Check for Barnaba pattern
        if "pairing" in basename or "stacking" in basename:
            return ExternalTool.BARNABA

        # Check for JSON files (DSSR)
        if basename.endswith(".json"):
            return ExternalTool.DSSR

        # Check header of .csv file for DNATCO
        if basename.endswith(".csv"):
            with open(file_path, "r") as f:
                line = f.readline().strip()
                if (
                    line
                    == "pdbid,model,family,class,chain1,nr1,res1,alt1,ins1,symmetry_operation1,chain2,nr2,res2,alt2,ins2,symmetry_operation2,confit,rmsd,curated_file,knn_metric,coplanarity_angle,coplanarity_shift1,coplanarity_shift2,coplanarity_edge_angle1,coplanarity_edge_angle2,C1_C1_yaw1,C1_C1_pitch1,C1_C1_roll1,C1_C1_yaw2,C1_C1_pitch2,C1_C1_roll2,hb_0_length,hb_0_donor_angle,hb_0_acceptor_angle,hb_0_OOPA1,hb_0_OOPA2,hb_1_length,hb_1_donor_angle,hb_1_acceptor_angle,hb_1_OOPA1,hb_1_OOPA2,hb_2_length,hb_2_donor_angle,hb_2_acceptor_angle,hb_2_OOPA1,hb_2_OOPA2,hb_3_length,hb_3_donor_angle,hb_3_acceptor_angle,hb_3_OOPA1,hb_3_OOPA2"
                ):
                    return ExternalTool.DNATCO

    # Default to MAXIT if no patterns match
    return ExternalTool.MAXIT

parse_external_output(file_paths, tool, structure3d)

Parse the output from an external tool (FR3D, DSSR, etc.) and convert it to BaseInteractions.

Parameters:

Name	Type	Description	Default
file_paths	List[str]	List of paths to external tool output files	required
tool	ExternalTool	The external tool that generated the output	required
structure3d	Structure3D	The 3D structure parsed from PDB/mmCIF	required

Returns:

Type	Description
BaseInteractions	BaseInteractions object containing the interactions found by the external tool

Source code in src/rnapolis/adapter.py

def parse_external_output(
    file_paths: List[str], tool: ExternalTool, structure3d: Structure3D
) -> BaseInteractions:
    """
    Parse the output from an external tool (FR3D, DSSR, etc.) and convert it to BaseInteractions.

    Args:
        file_paths: List of paths to external tool output files
        tool: The external tool that generated the output
        structure3d: The 3D structure parsed from PDB/mmCIF

    Returns:
        BaseInteractions object containing the interactions found by the external tool
    """
    if tool == ExternalTool.FR3D:
        return parse_fr3d_output(file_paths, structure3d)
    elif tool == ExternalTool.DSSR:
        return parse_dssr_output(file_paths, structure3d)
    elif tool == ExternalTool.MAXIT:
        return parse_maxit_output(file_paths, structure3d)
    elif tool == ExternalTool.BPNET:
        return parse_bpnet_output(file_paths, structure3d)
    elif tool == ExternalTool.RNAVIEW:
        return parse_rnaview_output(file_paths, structure3d)
    elif tool == ExternalTool.BARNABA:
        return parse_barnaba_output(file_paths, structure3d)
    elif tool == ExternalTool.MCANNOTATE:
        return parse_mcannotate_output(file_paths, structure3d)
    elif tool == ExternalTool.DNATCO:
        return parse_dnatco_output(file_paths, structure3d)
    else:
        raise ValueError(f"Unsupported external tool: {tool}")

process_external_tool_output(structure3d, external_file_paths, tool, input_file_path, find_gaps=False, decompose_pseudoknot_free=False)

Process external tool output and create a secondary structure representation.

This function can be used from other code to process external tool outputs and get a Structure2D object with the secondary structure information.

Parameters:

Name	Type	Description	Default
structure3d	Structure3D	The 3D structure parsed from PDB/mmCIF	required
external_file_paths	List[str]	List of paths to external tool output files (empty for MAXIT)	required
tool	ExternalTool	The external tool that generated the output (FR3D, DSSR, etc.)	required
input_file_path	str	Path to the input file (used when external_file_paths is empty)	required
find_gaps	bool	Whether to detect gaps in the structure	False
decompose_pseudoknot_free	bool	If True, structural elements are decomposed from the pseudoknot-free structure while retaining pseudoknot characters in dot-bracket strings. Pseudoknotted stems are reported separately.	False

Returns:

Type	Description
Tuple[Structure2D, Mapping2D3D]	A tuple containing the Structure2D object and the Mapping2D3D object.

Source code in src/rnapolis/adapter.py

def process_external_tool_output(
    structure3d: Structure3D,
    external_file_paths: List[str],
    tool: ExternalTool,
    input_file_path: str,
    find_gaps: bool = False,
    decompose_pseudoknot_free: bool = False,
) -> Tuple[Structure2D, Mapping2D3D]:  # Added Mapping2D3D to return tuple
    """
    Process external tool output and create a secondary structure representation.

    This function can be used from other code to process external tool outputs
    and get a Structure2D object with the secondary structure information.

    Args:
        structure3d: The 3D structure parsed from PDB/mmCIF
        external_file_paths: List of paths to external tool output files (empty for MAXIT)
        tool: The external tool that generated the output (FR3D, DSSR, etc.)
        input_file_path: Path to the input file (used when external_file_paths is empty)
        find_gaps: Whether to detect gaps in the structure
        decompose_pseudoknot_free: If True, structural elements are decomposed from the
            pseudoknot-free structure while retaining pseudoknot characters in
            dot-bracket strings. Pseudoknotted stems are reported separately.

    Returns:
        A tuple containing the Structure2D object and the Mapping2D3D object.
    """
    # Parse external tool output
    if not external_file_paths:
        # For MAXIT or when no external files are provided, use the input file
        file_paths_to_process = [input_file_path]
    elif tool == ExternalTool.MCANNOTATE or tool == ExternalTool.RNAVIEW:
        # MC-Annotate and RNAView requires both the stdout and the PDB file
        file_paths_to_process = external_file_paths + [input_file_path]
    else:
        # Process all external files
        file_paths_to_process = external_file_paths

    base_interactions = parse_external_output(file_paths_to_process, tool, structure3d)

    # Extract secondary structure using the external tool's interactions
    return structure3d.extract_secondary_structure(
        base_interactions, find_gaps, decompose_pseudoknot_free
    )