You should already have logged in to the web application and created a provider record, as was described in the preceding section.
The first step in creating a new Reciprocal Net sample is to create its metadata record using the web application. Click the Submit Sample button on the menu bar to go to the submission form. Notice that the lab with which your user account is associated is being recorded in the sample’s metadata. In the next field you should choose the provider that delivered this crystal sample to you. You may create new provider records, if needed, via the Administrative Tools feature that was described above. A sample’s associated provider cannot be changed once the sample record has been created. You may enter the sample’s anticipated empirical formula, if the provider gave you some idea what it might be. You may also enter the name of the person within the provider’s lab who actually delivered the sample to you.
Every Reciprocal Net sample must be assigned a unique sample number that identifies the sample within the context of your lab. It is not necessary for your sample number to be globally unique (across all of the Reciprocal Net Site Network), just for it to be unique within your lab. The sample number may be up to 32 characters long and may contain letters and symbols if you like. Many crystallography labs prefer to use a separate system for tracking samples submitted, using their own ID numbers. If your lab fits into this category you’ll want to specify that tracking number here. Or, you could configure your server to auto-generate sequential sample numbers according to rules you specify. (See page 46.) It is very not possible to change a sample number once the sample record has been created, so choose wisely. Enter any comments you like and then click the Submit button.
Your browser should be delivered to the Edit sample page, where you can see details about this sample record and make changes to it. The next step in creating a new sample is to create its data directory in the repository; it’s easiest if you do this via the web application. Scroll to near the bottom of the Edit sample page, in the section that begins with a message something like No files for xxx in repository. Every sample should have a corresponding directory in the repository where the sample’s data files can be stored. In a default site software installation, the files are stored somewhere beneath /var/recipnet/data/, usually under a directory named for the sample’s originating lab and then under a directory named for the sample number. Every sample has its own data directory, and this directory name must match the sample number. Some labs find it more convenient to organize their sample data directories into deeper hierarchies (perhaps with sample directories grouped into parent directories according to the year they were created, for example). This is an optional feature, but if you choose to use it you’ll need to specify the “grouping directory” name in this box. If you do not wish to use this feature, and you’re satisfied with all your sample data directories living in the same parent directory without any additional hierarchy, you may safely leave this box blank. Click the Create button to continue. The section of the Edit sample page that displayed a warning message before now contains a list of all the data files associated with this sample. No files will appear in this section, however, until you upload them to the server.
After you have submitted a new sample record and created its directory in the repository, the next thing you do to a real-world crystal sample is put it on your diffractometer and collect some data. Once data collection has completed, you’ll want to return to the Edit sample page in the web app and click the Collect preliminary data link in the menu at the bottom of the page. The Collect preliminary data page gives you an opportunity to record information garnered from the collection operation – all fields are optional. You may specify the name of the crystallographer who collected the data (if more than one crystallographer was involved you may enter several names), the unit cell parameters (these can be changed later), the temperature at which data was gathered, a short (one-word) description of the crystal’s color, and general comments about the collection operation. Click the Save button when you’ve finished filling out the form.
Once data has been collected from the real-world crystal sample and the operation recorded within the recipnet web app, the next step is usually to solve the structure and refine it. Unfortunately Reciprocal Net cannot help you with this part. But once the structure has been refined, be sure to visit the Edit sample page and click the Refine structure link. The Refine structure page allows you to record more information about the sample – again all fields are optional. The unit cell parameters specified on the Collect preliminary data page previously may be changed here; you may enter a summary of the structure if you wish; you may enter z and the space group, several statistical indicators of your data’s accuracy (goodness of fit, RF, R(F2), RWF, RW(F2)), and an empirical formula, structural formula, moiety formula, SMILES code, trade name, common name, and IUPAC (formal) name. Enter information in as many of these fields as you’re able and then hit the Save button.
Your sample record is now in the Complete state and might stay this way for many months or years. The sample’s provider, if he has a user account on your site, will be able to look his sample up and access the data you collected, as will fellow staffers who at your crystallography lab. Now is a good time to attach data files to your sample – like an industry-standard cif file or a crt file so that JaMM will work. All data files associated with samples that you create are stored on your server in the repository, somewhere beneath the directory /var/recipnet/data/. For instance, if you gave your sample the number ‘123’ and the name of your lab was ‘abc’, and you chose not to use a “grouping directory”, all the sample’s data files should be placed in the directory /var/recipnet/data/xyz/123/. This directory should have already been created when you clicked the Create button earlier in this section. (Due to potential permissions and security issues, the site software web application is the preferred method for creating repository directories.)
You may upload data files to the server from your desktop computer via any of several mechanisms. Click the Upload files button near the lower-left corner of the page. You’ll see the Upload Files page, where you can upload up to five files from your desktop computer to the server. Click a Browse button, choose a file from your local system, and click the Upload now button. The file is uploaded and a confirmation page appears. Subsequently you see the Manage Files page, which lists all sample data files attached to the sample and can manipulate them as need.
Another method for uploading files is via dragging-and-dropping to the web application. This is particularly effective if you have many files to transfer at once. On the Manage Files page, look in the lower-right corner and click on the link for Upload files (Drag-and-Drop). The next page that appears contains a Java applet that helps you upload files. (If you see a security warning, please authorize the applet to run.) Arrange the windows on your screen so that you see both the web page and your local computer’s file manager at the same time. Find a sample data file that you wish to upload within your desktop computer’s file manager. Click on a file icon, drag the file into your web browser window, and drop the file onto the applet. A progress bar appears and the file is uploaded to the server. You can repeat the procedure for several files. You also can select several files on your desktop and drag all of them to the applet at once. When you’ve finished, click the Save button. A moment later you should see the Manage Files page again. Look in the lower-right corner and click the link Back to “Edit Sample”. Notice that links to the sample’s attached data files have appeared on the bottom-left side of the page.
There are other ways to transfer sample data files to your server as well. Reciprocal Net site software automatically detects and recognizes sample data files that are deposited into existing repository directories on the server’s filesystem. Thus, services like ftp, ssh (and related utilities), nfs, samba, etc. are useful for this purpose. Pretty much any of these mechanisms will require that the user transferring data files have a GNU/Linux user account on the server and write permissions on at least some portion of the repository.
The last step in dealing with a Reciprocal Net sample is releasing it to the public. This is the chief motivation behind the Reciprocal Net site software – making it as easy as possible for you to contribute your samples to the distributed public collection. In deference to intellectual property issues, most labs choose to publish samples on Reciprocal Net only after the same structure has been published in a trade journal (usually by the sample’s provider), possibly several years after the Reciprocal Net sample reached the complete state. This ensures that the prior-publication rights of the sample provider are not infringed. Reciprocal Net also encourages its member labs to institute a policy that samples that have gone unpublished for five years or more (for example) are automatically released to the public by the crystallography lab staff.
To release a sample to the public, go to the Edit sample page and click the Release to public link. The Release to public page allows you to enter a few additional metadata items (all optional): a layman’s explanation of the sample’s real-world significance, a preferred name if there are several from which to choose, a copyright notice for your data and metadata, and comments about why the sample is being released to the public. The layman’s explanation is particularly valuable if you intend to contribute your sample to the “Common molecules collection” maintained by Reciprocalnet.org but may be of limited use otherwise. The copyright notice is optional, but if you find your lab’s employees typing the same notice for many samples, you might want to go to Administrative Tools and Edit lab to change the default copyright notice that appears on samples released from your lab. Click the Submit button to release the sample to the public.
Unauthenticated visitors to your web site now will see the sample in the searches they run, and your sample will be indexed by the distributed search engine on Reciprocalnet.org very soon. Congratulations on releasing your first sample.