Cite your research

Extension documentation is not only about marketing a release. It is also where you give users the scientific and technical context they need to trust and cite your work.

In practice, developers usually want to expose four kinds of information:

• papers that should be cited when the extension is used
• third-party libraries or datasets the extension depends on
• brief usage or scientific context
• version-specific notes and release changes

SAMSON gives you two complementary places to provide that information:

• inside the extension UI, through a citable window
• on the extension page on SAMSON Connect

Cite in a SAMSON Extension

Note

Citation in a SAMSON Extension can be visible to users only if the SAMSON Extension has some GUI.

Use this approach when you want citation information to be available directly from an app window or a model property window.

First, add the SBGWindow::Citable flag in the getFormat implementation (see SBGWindowWidget::getFormat) of your GUI widget:

int SEEMyModelProperties::getFormat() const {

    // SAMSON Extension generator pro tip: modify these default settings to configure the window
    //
    // SBGWindow::Savable : let users save and load interface settings (implement loadSettings and saveSettings)
    // SBGWindow::Lockable : let users lock the window on top
    // SBGWindow::Resizable : let users resize the window
    // SBGWindow::Citable : let users obtain citation information (implement getCitation)

    return (SBGWindow::Savable | SBGWindow::Lockable | SBGWindow::Citable);

}

This adds a question-mark button to the window chrome:

Then implement SBGWindowWidget::getCitation:

QString    SEEMyModelProperties::getCitation() const {

    return
        "If you use this interaction model in your work, please cite:<br/>"
        "<br/>"
        "[1] S. Artemova, L. Jaillet and S. Redon.<br/>"
        "    Automatic molecular structure perception for the universal force field.<br/>"
        "    J. Comput. Chem. 2016, 37, 1191-1205. DOI: 10.1002/jcc.24309.<br/>"
        "<br/>"
        "[2] <a href=\"https://www.samson-connect.net\">https://www.samson-connect.net</a><br/>"

}

The returned string can use the HTML subset supported by Qt, which is useful for links, line breaks, and simple formatting.

When the user clicks the citation button, SAMSON shows a modal dialog that displays the citation text and lets the user copy it to the clipboard:

This is the right place for:

• citation-ready paper references
• a short explanation of what should be cited and when
• links to project or documentation pages
• explicit acknowledgment of external libraries when appropriate

Cite on SAMSON Connect

Use the SAMSON Connect page for everything that should be visible before installation: screenshots, overview text, links, public release notes, and longer descriptions.

First upload the extension as described in Publishing a SAMSON Extension.

The description field on SAMSON Connect supports Markdown based on the CommonMark specification, so you can add:

• links to papers, repositories, and documentation
• formatted lists of references
• release notes and change summaries
• images that explain the workflow or results

If needed, review a Markdown refresher at Learn X in Y Minutes.

A good default documentation split

For many extensions, the clearest split is:

• put the short, copyable citation text in the extension UI
• put the richer overview, links, screenshots, and release notes on SAMSON Connect

That gives users both a quick in-product citation path and a fuller public documentation page.