ARC Commander QuickStart

This guide introduces the ARC Commander, a command line tool to create, edit and share you ARC. It requires some experience with the command line (command prompt, shell, terminal,…).

Tip

Before following this guide, we recommend to explore the Getting Started guide for a more comprehensive overview of ARC concepts and features.

Here we reproduce parts of Viola’s example ARC created there. However, the ARC Commander by design does not offer all functions you know from ARCitect. For metadata annotations you can either work on your ARC in ARCitect as explained in the Getting Started guide or explore the different options of using Swate.

Setup

Section titled Setup

Before using the ARC commander, please install Git, Git-LFS and ARC Commander and setup access to your DataHUB account.

1. Install and setup Git and Git-LFS

   In order to use the ARC Commander, Git (version ≥ 2.32.0) and Git LFS must be installed on your computer.

   Tip

   The ARC Commander checks for presence of Git and Git LFS and results in an error, if not installed.

   Download and install Git and Git LFS

   Section titled Download and install Git and Git LFS

   Please install Git and Git LFS

   • On Windows Git LFS may already be installed during your Git installation
   • For macOS we recommend to install via homebrew as described on the site above

   Check your Git installation

   Section titled Check your Git installation

   To check, that Git and Git LFS are installed on your computer, open a new command prompt or terminal and execute the following two commands. These should display the installed version.

   git --version

   git-lfs --version

   Tip

   Recommended Git version ≥ 2.32.0

   Initialize Git LFS

   Section titled Initialize Git LFS

   After installation of Git LFS you must run the following command once to make sure Git LFS is initialized on your system.

   git lfs install

   Configure Git

   Section titled Configure Git

   Git always signs “commits” with a user name and e-mail address. These are then also used by the DataHUB to associate the commits to your user account.

   To add your user name and email address to the git configuration on your computer, run the following two commands in a command prompt or terminal. Make sure to replace “Your DataHUB Name” and “Your DataHUB Email Address” with your information from the DataHUB.

   1. Your name

   git config --global user.name "Your DataHUB Name"

   2. Your email address

   git config --global user.email "Your DataHUB Email Address"

   Tip

   Configuration needs to be done only once after installation of git on your system.

   Check your Git configuration

   Section titled Check your Git configuration

   Run this command to display your user configuration

   git config --global --get-regexp user

2. Install ARC Commander

   In order to use the ARC Commander, Git (version ≥ 2.32.0) and Git LFS must be installed on your computer.

   Tip

   The ARC Commander checks for presence of Git and Git LFS and results in an error, if not installed.

   Download and install Git and Git LFS

   Section titled Download and install Git and Git LFS

   Please install Git and Git LFS

   • On Windows Git LFS may already be installed during your Git installation
   • For macOS we recommend to install via homebrew as described on the site above

   Check your Git installation

   Section titled Check your Git installation

   To check, that Git and Git LFS are installed on your computer, open a new command prompt or terminal and execute the following two commands. These should display the installed version.

   git --version

   git-lfs --version

   Tip

   Recommended Git version ≥ 2.32.0

   Initialize Git LFS

   Section titled Initialize Git LFS

   After installation of Git LFS you must run the following command once to make sure Git LFS is initialized on your system.

   git lfs install

   Configure Git

   Section titled Configure Git

   Git always signs “commits” with a user name and e-mail address. These are then also used by the DataHUB to associate the commits to your user account.

   To add your user name and email address to the git configuration on your computer, run the following two commands in a command prompt or terminal. Make sure to replace “Your DataHUB Name” and “Your DataHUB Email Address” with your information from the DataHUB.

   1. Your name

   git config --global user.name "Your DataHUB Name"

   2. Your email address

   git config --global user.email "Your DataHUB Email Address"

   Tip

   Configuration needs to be done only once after installation of git on your system.

   Check your Git configuration

   Section titled Check your Git configuration

   Run this command to display your user configuration

   git config --global --get-regexp user

3. Register for a DataPLANT account

   With a DataPLANT account you can use the DataHUB and share your ARC for collaboration.

   Registration

   Section titled Registration

   Please register here.

   

   DataPLANT roles

   Section titled DataPLANT roles

   During the registration you can “Choose your role in DataPLANT”:

   • DataSteward
     • Member of / associated to DataPLANT
     • Teaches DataPLANT tools and services to community members
   • Developer
     • Member of / associated to DataPLANT
     • Develops DataPLANT tools and services
   • Member
     • Other member of DataPLANT
   • User
     • User who want to use the DataPLANT tools and services

   

   DataPLANT account settings

   Section titled DataPLANT account settings

   If you want to adjust your account settings, simply click the login icon in the navigation bar on this site.

   • In the tab “Password” you can modify your password.
   • In the tab “Authenticator” you can set up Two Factor Authentication (2FA).
4. Setup DataHUB access

   The DataHUB allows you to share your ARCs with registered lab or project partners. After registration, you need to setup the ARC Commander for smooth ARC synchronization between your computer and the DataHUB.

   Tip

   This needs to be done only once per computer.

   Enable Git to store credentials on your computer

   Section titled Enable Git to store credentials on your computer

   Open a command prompt or terminal and execute the following command(s)

   Windows / Linux

   Section titled Windows / Linux

   git config --global credential.helper store

   MacOS

   Section titled MacOS

   git config --global credential.helper osxkeychain

   Receive and store a DataHUB access token

   Section titled Receive and store a DataHUB access token

   arc remote accesstoken get -s https://git.nfdi4plants.org

   A browser window will open asking for your DataPLANT login. After login you are asked to authorize your computer to communicate with the DataHUB. In case you are already logged in, the browser will directly display a plain Success message to you.

   Tip

   This authenticates your computer to communicate with your personal DataHUB account

   Tip

   After two hours you have to repeat this process as this token will expire. Have a look at the next section to learn how to create a longer lasting token (e.g. for large data uploads).

   Store a configurable DataHUB access token for your project

   Section titled Store a configurable DataHUB access token for your project

   Access tokens created with the ARCommander expire after two hours. To create a longer-lasting access token for your project, follow these steps:

   1. Create a project access token

      This guide shows you how to generate a Project Access Token. Project Access Token are similar to Personal Access Token, but Project Access Tokens are scoped to a project, so you cannot use them to access resources from other projects.

      1. Sign in to the DataHUB
      2. Open your Project (ARC)
      3. Navigate to ‘Settings’ (1), then ‘Access Tokens’ (2):
      4. Choose a name for your token (1), set an expiration date (optional) (2), assign a role (3), configure permissions (4), and create your token (5):
      5. Once created, you can copy the token:

      Note

      Make sure you save your token, because it is only displayed once.

   2. Store the token in your local ARC

      arc remoteaccess accesstoken store --token <replaceWithYourToken>

   Once set up, you will not need to authenticate yourself (e.g., by manually retrieving a token through ‘arc remote token get’) until the token expires. When switching to another machine you have to repeat the process.

Initialize your ARC

Section titled Initialize your ARC

1. Create and navigate to a local folder, which you want to initialize as an ARC, e.g. via file explorer or

   mkdir AthalianaColdStressSugar
   cd AthalianaColdStressSugar

2. Initialize your ARC by executing

   arc init

This created the general ARC folder structure:

• studies
• assays
• workflows
• runs
• isa.investigation.xlsx

Add investigation metadata

Section titled Add investigation metadata

1. Add an investigation identifier (-i or --investigationidentifier)

   arc investigation update -i AthalianaColdStressSugar

   Tip

   Avoid using spaces or special characters in the identifier.

2. Add a Title

   arc investigation --title "Arabidopsis thaliana cold acclimation"

3. Add a Description

   arc i --description "This experiment investigates the response of Arabidopsis thaliana to cold stress by subjecting plants to low-temperature conditions and monitoring physiological, molecular, and growth-related changes. Cold-treated plants are compared with control groups grown under optimal conditions to assess stress-related markers such as changes in protein abundance, sugar content, and growth rates. The goal is to identify key molecules and physiological responses involved in cold tolerance, contributing to the understanding of plant stress adaptation mechanisms."

4. Add Contacts

   arc i person register -f Jasmine -l Beetroot
   arc i person register -f Oliver -l Sage
   arc i person register -f Viola -l Canina --email viola@plantscience.xyz

Add studies and assays

Section titled Add studies and assays

1. Add a study with an identifier (-s, --assayidentifier)

   arc study add -s AthalianaColdStress

2. Add assays with an identifier (-a, --assay)

   arc assay add -s AthalianaColdStress -a SugarMeasurement
   arc assay add -s AthalianaColdStress -a Proteomics_MS
   arc assay add -s AthalianaColdStress -a Proteomics_DataAnalysis

   Note

   An assay must be linked to a study. If a study does not exist, it will be created automatically in this step.

The ARC Commander will add subdirectories to the studies and assays folders. Your ARC should look similar to this now:

• Directorystudies

  • DirectoryAthalianaColdStress

    • resources
    • protocols
    • isa.study.xlsx
  • …
• Directoryassays

  • DirectorySugarMeasurement

    • dataset
    • protocols
    • isa.assay.xlsx
  • …
• Directoryworkflows

  • …
• Directoryruns

  • …
• isa.investigation.xlsx

Sync with the DataHUB

Section titled Sync with the DataHUB

1. Synchronize your ARCs with the DataHUB using the command

   arc sync

2. If you did not connect your local ARC with a remote one so far, you can specify the remote address (-r or --remote) followed by the DataHUB URL, e.g.,

   arc sync -r https://git.nfdi4plants.org/<YourUserName>/<YourARC>

3. If no ARC exists under the given URL, you can force (-f or --force) the ARC Commander to create it.

   arc sync -f

   Note

   This will prompt an Error ERROR: GIT: fatal: repository 'https://git.nfdi4plants.org/<YourUserName>/<YourARC>' not found (Windows) or ERROR: GIT: fatal: couldn't find remote ref main (macOS). Don’t worry, the ARC is being created at that DataHUB during this step.

4. Check if the upload was successful by visiting your ARC at the respective URL in your browser.

Seeking help

Section titled Seeking help

The ARC Commander comes with a leveled help menu, that suggests suitable inputs on every level of command or subcommand. You can simply add -h or --help at the end of an ARC Commander action to display the respective help menu.

Some examples:

arc --help

arc investigation --h

arc investigation create --help

arc study --h

arc study add --help

arc assay remove --help

What’s next?

Section titled What’s next?

Here we only introduced the basic functions. After concluding this quickstart, you might want to explore the ARC Commander manual for a more detailed usage instruction.

In order to annotate the data in your ARC, explore the sections on studies and assays in the Getting Started guide. You can do this with ARCitect or Swate.

Tip

You were looking for even more code? Check out the ARCtrl docs for fully-fledged code control over ARCs.