Skip to content
Snippets Groups Projects
user avatar
Michal Malý authored
1df84ab8
History

WebMMB PHP client

WebMMB PHP client is a PHP wrapper around WebMMB service API. WebMMB PHP enables easy interfacing with WebMMB service directly from PHP. WebMMB PHP requires at least PHP 7. (Compatibility with older versions is possible but untested).

Example usage

Trivial example that issues a WebMMB job to form a simple tetraloop.

<?php
require_once('Session.inc');
require_once('Types.inc');

// URL of the WebMMB service
$URL = 'https://webmmb.somewhere.awesome.net';

try {
    // Create a new WebMMB session
    $session = \WebMMB\Session::create($URL);

    // Create a new WebMMB job
    $session->createJob('Tetraloop');

    // Prepare data for job commands
    // RNA biomolecule to work with
    $rna = new \WebMMB\Compound(
        'A',                       // Chain
        \WebMMB\CompoundType::RNA, // Compound type
        'UACGUAAGUA',              // Sequence
        2639                       // Author number of the first residue
    );
    // Specify double helix pairing
    $dh = new \WebMMB\DoubleHelix(
        'A',
        $rna->authToSeq(2639),
        $rna->authToSeq(2641),
        'A',
        $rna->authToSeq(2648),
        $rna->authToSeq(2646)
    );
    // NtCs to apply on structural conformation
    $conformations = [
        new \WebMMB\NtCConformation('A', $rna->authToSeq(2639), $rna->authToSeq(2642), 'AA00', 1.5),
        new \WebMMB\NtCConformation('A', $rna->authToSeq(2642), $rna->authToSeq(2643), 'OP03', 1.5),
        new \WebMMB\NtCConformation('A', $rna->authToSeq(2643), $rna->authToSeq(2644), 'AA08', 1.5),
        new \WebMMB\NtCConformation('A', $rna->authToSeq(2644), $rna->authToSeq(2648), 'AA00', 1.5)
    ];
    $ntcs = new \WebMMB\NtCs(
        $conformations,  // List of NtC conformations to apply
        3000             // NtC force scale factor - 3000 is the recommended default value
    );
    // Create StandardCommands object
    $commands = new \WebMMB\StandardCommands(
        1, // First stage
        1, // Last stage
        2, // Reporting interval
        10, // Total number of reporting intervals
    );
    // Set up additional parameters
    $commands->compounds = [ $rna ]; // StandardCommands expects an array of compounds
    $commands->double_helices = [ $dh ];
    $commands->ntcs = $ntcs;

    // Start the job
    $session->startJob('Tetraloop', $commands, []);

    $info = $session->jobInfo('Tetraloop');
    while (true) {
        // Keep checking in on the job progress
        $info = $session->jobInfo('Tetraloop');
        if ($info->state === \WebMMB\JobState::Finished || // Job has successfully completed
            $info->state === \WebMMB\JobState::Failed) {   // Job did not complete successfully
            break;  // In either case, stop waiting for the job to finish.
        }

        $step = $info->current_step;
        $total = $info->total_steps;
        if ($step === null || $total === null) {
            // No steps info - MMB is preparing to launch the job
            echo "Job is being initialized...\n";
        } else {
            echo "Job is running step {$step} of {$total} total steps\n";
        }

        sleep(1);
    }

    if ($info->state === \WebMMB\JobState::Finished) {
        // Job complete, let us get the the final structure
        $struct = $session->getStructure('Tetraloop', 1); // Get structure for stage 1 of job 'Tetraloop'
        file_put_contents('tetraloop.pdb', $struct);
    } else {
        // Something went wrong. Get the MMB diagnostic output and find out what went wrong
        echo $session->mmbOutput('Tetraloop') . "\n";
    }
} catch (\WebMMB\ServerError $ex) {
    // Is the service talking to us?
    echo $ex->getMessage() . "\n";
} catch (\WebMMB\InvalidOperationError $ex) {
    // Are we calling the PHP wrapper correctly?
    echo $ex->getMessage() . "\n";
} catch (\WebMMB\InvalidDataError $ex) {
    // Is our data always valid?
    echo $ex->getMessage() . "\n";
} catch (\WebMMB\ErrorResponse $ex) {
    // Are we calling the W````ebMMB service correctly?
    echo $ex->getMessage() . "\n";
}

More complex example for a density fitting job

<?php

require_once('Session.inc');
require_once('Types.inc');

// URL of the WebMMB service
$URL = 'https://webmmb.somewhere.awesome.net';

try {
    // Create a new WebMMB session
    $session = \WebMMB\Session::create($URL);

    $JOB_NAME = 'Density fit';
    // Create a new WebMMB job
    $session->createJob($JOB_NAME);

    // Prepare data for job commands
    // Load structure and density map files
    $struct_file = \WebMMB\AdditionalFile::local(
        'structure.pdb',        // Name of the file that is used to identify it within WebMMB service. Mind that MMB may require the file to have a particular suffix
        'T0202.pdb',            // Path to the file on local filesystem
        function ($report) {    // Optional callback for progress reporting
            echo "Uploading file {$report->getFile()->getName()}, {$report->getPercentDone()} % done...\n";
        }
    );
    $density_file = \WebMMB\AdditionalFile::local(
        'density.map',
        'T0202.map',
        function ($report) {
            echo "Uploading file {$report->getFile()->getName()}, {$report->getPercentDone()} % done...\n";
        }
    );

    // Create StandardCommands object
    $commands = new \WebMMB\DensityFitCommands(
        'structure.pdb', // Name of structure file as given before
        'density.map',   // Name of the density file
        2, // First stage - stage number must be at least 2 for density fitting job
        2, // Last stage
        2, // Reporting interval
        10, // Total number of reporting intervals
    );
    // Add dummy compounds - we need them if we also want to specify
    // mobilizers or NtCs
    // Note that we would have to provide correct residue numbers too if we
    // wanted to specify NtC or more fine-grained mobilizers
    $commands->compounds = [
        new \WebMMB\Compound('A', \WebMMB\CompoundType::Protein, '', []),
        new \WebMMB\Compound('B', \WebMMB\CompoundType::Protein, '', []),
        new \WebMMB\Compound('C', \WebMMB\CompoundType::Protein, '', []),
        new \WebMMB\Compound(
            new \WebMMB\Chain('D', 'P'),  // When chain name and author chain name do not match, we need to provide the proper mapping
            \WebMMB\CompoundType::Protein,
            '',
            []
        ),
        new \WebMMB\Compound(
            new \WebMMB\Chain('E', 'T'),
            \WebMMB\CompoundType::Protein,
            '',
            []
        ),
    ];
    // Add the mobilizers
    $commands->mobilizers = [
        new \WebMMB\Mobilizer(\WebMMB\BondMobility::Rigid, 'A'),
        new \WebMMB\Mobilizer(\WebMMB\BondMobility::Rigid, 'B'),
        new \WebMMB\Mobilizer(\WebMMB\BondMobility::Rigid, 'C'),
        new \WebMMB\Mobilizer(\WebMMB\BondMobility::Free, 'D'),
        new \WebMMB\Mobilizer(\WebMMB\BondMobility::Free, 'E')
    ];

    // Start the job
    // Additional files will be uploaded automatically
    $session->startJob($JOB_NAME, $commands, [ $struct_file, $density_file ]);

    $info = $session->jobInfo($JOB_NAME);
    while (true) {
        // Keep checking in on the job progress
        $info = $session->jobInfo($JOB_NAME);
        if ($info->state === \WebMMB\JobState::Finished || // Job has successfully completed
            $info->state === \WebMMB\JobState::Failed) {   // Job did not complete successfully
            break;  // In either case, stop waiting for the job to finish.
        }

        $step = $info->current_step;
        $total = $info->total_steps;
        if ($step === null || $total === null) {
            // No steps info - MMB is preparing to launch the job
            echo "Job is being initialized...\n";
        } else {
            echo "Job is running step {$step} of {$total} total steps\n";
        }

        sleep(1);
    }

    if ($info->state === \WebMMB\JobState::Finished) {
        // Job complete, let us get the the final structure
        $struct = $session->getStructure($JOB_NAME, 2);
        file_put_contents('fitted.pdb', $struct);
    } else {
        // Something went wrong. Get the MMB diagnostic output and find out what went wrong
        echo $session->mmbOutput($JOB_NAME) . "\n";
    }
} catch (\WebMMB\ServerError $ex) {
    // Is the service talking to us?
    echo $ex->getMessage() . "\n";
} catch (\WebMMB\InvalidOperationError $ex) {
    // Are we calling the PHP wrapper correctly?
    echo $ex->getMessage() . "\n";
} catch (\WebMMB\InvalidDataError $ex) {
    // Is our data always valid?
    echo $ex->getMessage() . "\n";
} catch (\WebMMB\ErrorResponse $ex) {
    // Are we calling the WebMMB service correctly?
    echo $ex->getMessage() . "\n";
}