Tech Guides
- Ensure that you are either connected to the on-campus MUSC Wifi network OR that you are connected to the MUSC VPN.
- Further instructions for connecting via the MUSC VPN here.
- Open a Finder window.
- In the top left toolbar, click “Go”, select “Connect to Server” at the bottom of the list.
- In the top search bar, enter the server address.
- (You can also click the plus (+) button in the bottom left corner of the connection box in order to add this address to your list for easier access next time.)
- Click “Connect” and enter your netID and password when prompted.
- You can elect to have the connection tool remember your net ID for easier access next time.
- Ensure that you are either connected to the on-campus MUSC Wifi network OR that you are connected to the MUSC VPN.
- Further instructions for connecting via the MUSC VPN here.
- On the sidebar, navigate to “Network”, right click, and select “Map network drive…”
- In the folder search bar, enter the server address.
- Click the checkbox “Reconnect at sign-in” for easier access next time.
- Click the checkbox “Connect using different credentials”
- In the credentials window, click “More choices” and select “Use a different account”.
- Enter “clinlan[your netID]” and your netID password and click “Connect”.
- Your VPN connection (if applicable) – ensure that you are connected to the VPN.
- The address of the server – make sure that the address is entered correctly and that there are no spaces or extraneous characters.
- Your internet connection – ensure that you are connected to the internet.
Note: all processing times are estimated using locally stored files; files stored on an external server may extend estimated times
You will need the following supplies:
- The CD burner
- A blank CD
- A CD sleeve
- A scrap file folder
- A neurology address label
- The return address label for the study in question
- A brown padded SealedAir envelope
- A copy of the image disclaimer (found on last page of this SOP
- The address of the individual to whom the disc is being mailed
- Horos dicom viewer
Instructions:
- Put a blank disc in the CD burner
- Open Horos
- Load in the images you want to burn in dicom form
- Make sure you have clicked on the entire subject folder in Horos and then click the ‘Burn’ button
- An options box will pop up
- Here are the parameters and options that should be set:
- When parameters are set, click the Burn symbol
- After about 1-2 minutes (depending on computer speed and amount of dicoms), a secondary option box will pop up
- If the box is not immediately visible, click the Horos thumbnail on your taskbar and the secondary box should show up
- Click ‘Burn’ on the secondary box
- A status bar should appear
- This process will take 3-10 minutes depending on computer speed and amount of dicoms
- While the CD is burning:
- Cut out a piece of the scrap folder that is big enough to wrap around the CD sleeve
- This is intended to provide an extra layer of protection and support for the CD
- Print out a copy of the image disclaimer (scroll down to the image disclaimer on the last page of this document, change the red ‘[your study]’ text to be the name of your study, print this SOP, and select ‘Current Page’)
- Cut out a piece of the scrap folder that is big enough to wrap around the CD sleeve
- When burn is complete, be sure to label the CD, the sleeve, and the protective folder covering with the subject ID
- Tape the protective covering closed on all sides
- Place CD package in brown envelope and seal package
- Place return address label on the top left corner on the front of the envelope
- Place the Neurology address label on the center back of the envelope
- Place envelope in the Outbound MUSC Business mailbox outside of the building
Note: This is only relevant if you are working on a Mac or Linux system or using a Windows Subsystem for Linux (WSL)
###What is bash and why should I use it?
When you open your Terminal on a Mac, what you see is a bash shell. This bash shell is an interface to your operating system. From here, you can input commands to access files or programs on your computer. Doing this will accomplish the same task as double clicking to open a program and then using the graphical user interface (GUI) of the program to interface with it. The main difference is that by using the Mac Terminal, you will interface with programs and files via the command line (CLI) instead of a GUI.
Being able to use bash is essential for most image analysis techniques discussed within this collective of documentation. For example, programs like Freesurfer and FSL become significantly more versatile by interfacing with them via bash. Plus, bash allows you to quickly move, delete, rename, copy, or otherwise reorganize long lists of files very quickly (along with many other convenient perks).
Here is a quick list of common, useful bash commands.
It will be helpful to get familiar with bash quickly by opening the Terminal and trying out some simple commands.
For example, if you want to copy a file, try using cp [/path/to/file.fileextention] [/new/file/location/file.fileextension] – you will replace the first path with the current file location and the second path with location you’d like your file to be.
Other useful commands that work with similar logic are rm (which will delete a file or folder you specify) and mv (which will move a file or folder you specify). Be careful with these as they will permanently change the file you give them.
I also recommend trying to accomplish simple tasks via bash by web searching how to do the tasks. For example “how to open text files with bash” or “how to delete all files with a specific file extension in bash”, etc.
Logical loops may also be useful to you. These will allow you to carry out commands across numerous files or folders depending on specific logic.
For example, say you have a dataset of diffusion data across numerous subjects and you want to preprocess all of the subjects with a single command. You could take your base command and put it inside of a for loop. Recall the PyDesigner command example from 01_Diffusion_Image_Analysis_101. If we wanted to execute that command across numerous subjects, we could set up a for loop that looks like this:
for ID in Subj1 Subj2 Subj3 ; do
pydesigner --denoise --degibbs --mask -w --force /desktop/user/PyDesigner-
Example/${ID}/nifti/DKI.nii, /desktop/user/PyDesigner-
Example/${ID}/nifti/B0.nii -o /desktop/user/PyDesigner-
Example/${ID}/pydesigner
done
Let’s walk through this command:
The first line contains the following elements:
“for” – this indicates that the following commands are going to be executed for every unit in a list
“ID” – this is a chosen variable that will stand in for each unit in the following list; this can be whatever you want. For this example, I chose “ID” to indicate that it will stand in for a list of subject IDs
“in” – this indicates that the list of items that will be affected by the commands is about to begin
“Subj1 Subj2 Subj3” – this is an example list of my subject names; this list could theoretically be a list of any series; no commas are necessary to distinguish one unit from another, spaces will do that.
“do” – this indicates that what comes next is the actual command
The indented set of lines is the actual command that will be executed based on the for loop you’ve set up above.
The important takeaway from this is the “${ID}” element. The dollar sign and brackets around our “ID” variable name tell the command that it will be iteratively going through a list we specified (Subj1 Subj2 Subj3)
For example, the command is going to take the path we’ve given it /desktop/user/PyDesigner-Example/${ID}/nifti/DKI.nii and it will sub in each unit in our list for the “${ID}” element by looking for the following paths:
/desktop/user/PyDesigner-Example/Subj1/nifti/DKI.nii
/desktop/user/PyDesigner-Example/Subj2/nifti/DKI.nii
/desktop/user/PyDesigner-Example/Subj3/nifti/DKI.nii
This is extremely same process will be carried out for the entire command so that each subject is processed through PyDesigner using only the single command within the for loop
“done” tells the for loop to close and run the commands wrapped inside of it.
In order to access software such as Freesurfer or FSL via your Terminal, it is first helpful to add these programs to your bash profile. This tells bash where the source codes for these programs live on your computer so that all you need to do is type specific commands into your terminal rather than entire paths to the code for each command.
As you can see in the example above, some pieces of software are set up to automatically add elements to your bash profile upon installation (such as MRtrix3). However, some elements need to be added manually.
You can do this by doing the following:
Open a terminal window
Type vi .bash_profile
When you see your bash profile open (which may be empty at first, type “i” (this stands for “insert” and will allow you to type things into the window that you will later save.
Start by adding a header to indicate which program you’re adding to your bash profile by using #. # at the beginning of a line indicates that a line is a comment and will not by read by any program as usable script. As you can see, I have headings for all programs beginning with # in my profile above.
Add whatever you need to add* dependent on the program. Typically, this will involve inputting export PATH=$PATH:/path-to-application/
Hit “Esc”, then “;” (the semi-colon), then “wq” (this stands for “write/save and quit”, then “enter”.
*If you are uncertain of what you need to add to your profile to get bash to recognize the program you want it to recognize, you can copy the lines in the example above based on the program in question. Or you can Google “add [program] to bash profile”
After you successfully add a program to your bash profile, you should be able to access all of the call-able commands the software offers. Such as “bet” or “flirt” from FSL or “recon-all” from Freesurfer.
Programs to consider adding to your bash profile: PyDesigner, FSL, MRIcroGL, Freesurfer, MRtrix3, or anything you will regularly call from your Terminal.
Note: This is a general guide to troubleshooting in general, not about a specific process or program. Most of the advice below is applicable to most processes or programs.
Let’s say you have a problem. You’re getting an error message when trying to carry about a process, or you can’t figure out how to set up a program to work the way you want, or your images don’t look as expected, etc.
Here is a general order of resources to turn to for help:
-
Try to solve the problem yourself.
- Before you even start turning to outside resources, try to solve the problem yourself. Just because you’ve received an unexpected outcome doesn’t mean you need outside help.
- Some common issues you can solve yourself include:
- Making sure all files and folders are where you expect them to be.
- Making sure all file paths you’re feeding into a process are correct.
- Making sure data copied correctly for one space to another.
- Making sure your code doesn’t have any syntax errors.
- Always make sure to check the small, simple things first.
-
Look at the resources you already have access to.
- Always start with what you have close at hand. This could be a software’s user guide, a paper that describes the pipeline you’re running, or even one of the documents within this documentation collective. If you can’t solve a problem yourself, you may already have a resource that can help.
-
Read online guides and forums.
- The internet will be a vast and often helpful resource for you.
- There are many blog entries, websites, and help guides online on a variety of topics – everything from MRI physics to bash syntax to image registration best practices to general computer issues.
- There are also help forums, which are a great resource for programming-centric problems, but other issues as well.
- Some helpful hints for effective web searching:
- If you are trying to solve an issue that involves an error message, search for the exact test of the error message.
- Be exact and specific.
- Instead of “how do I set my working directory in python” try “set working directory python3”
- If you don’t initially find what you need on your first search, try varying the detail and word usage in your searches.
- “printer not connecting to computer” maybe not be as effective as “Mac Mojave can’t connect to printer”.
- If you need with specific software, always try the manufacturer’s website first. Many developers also run help forums in addition to including helpful documentation on their websites.
- You can also try searching “[software/process name] forum”.
-
Post on online forums.
- You may encounter a scenario in which no resource can help you. This is rare but not unheard of. In this case, you may need to post a question on a forum. Here are some general guidelines for effective forum posting:
- But first, Check the forum thoroughly to make sure your question has not already been asked.
- Give a concise but descriptive title.
- For example: “Help with matlab problem” is a bad title. It tells the possible respondents nothing about your issue except that it is related to Matlab.
- “How can change colors of histogram in Matlab?” is a much better title.
- Contextualize your problem.
- In the body of the post, describe what you were doing when the error occurred, what you expected to happen, and what actually happened.
- Add supplementary materials when necessary.
- Most forums allow for adding in-line code or attachments to posts. Problems often become difficult to describe without visual aids. When in doubt, use these.
- Be courteous.
- People are more apt to answer a post if they believe the poster appreciates and values their input. It’s always nice to be nice.
-
Ask your colleagues.
- Some scenarios facilitate asking colleagues for help, such as when the above steps return no answers or when your questions are about in-house software or lab SOPs
- Feel free to reach out to your team members in person, via email, or via MS Teams when need be. And remember that it helps to take a similar approach to the guidelines for posting on online forums.
-
Reach out to authors or developers.
- At times it may be necessary to reach out to the authors of a paper, the developers of a software, or the person/people at the heart of the process/software/model/etc for which you are troubleshooting. Don’t be afraid to reach out of this is the case.
- Most people are happy to answer your questions if they have the time and capacity to do so. Just remember that this avenue generally takes longer to resolve because individual researchers or small development teams tend to be busy. Be sure to be respectful of people’s time.