help for sctomedia

Title

sctomedia -- rename and organize SurveyCTO media files

Syntax

sctomedia varname [if] [in], [by(varlist)] id(varname) vars(varlist) mediafolder(folder_path) outputfolder(folder_path)
resolve(varname)

You may enclose folder_path in double quotes.

id(varname) Specifies the ID variable.

by(varlist) Specifies the variables to be used to create folders, up to three levels. [optional]

vars(varlist) Specifies the variables to be included in the new media filename.

mediafolder(folder_path) Source folder of media files.

outputfolder(folder_path) Destination folder of media files.

resolve(varname) Indicates a second ID variable. [required when id(varname) has duplicates]

Description

sctomedia creates copies of SurveyCTO media files in a specified folder with user-friendly
names constructed from values stored in your dataset. This includes images, audio, video and text media
files. This command can also optionally organize such files into a folder structure, named using
values stored in your data.

This resource only works with data exported using SurveyCTO Sync, which 1) creates
a local folder named ‘media’ with all collected media files and 2) includes the file path (‘media\filename’)
in the dataset. Data exported directly from the server console webpage or via the API contains URLs to files as
opposed to just the file names assumed by this command.

Options

id(varname) specifies the ID variable of the dataset that will be used as the first component of the media files names.
If the ID variable is not a unique identifier to the observations in the dataset, it will throw an error requiring the option resolve()
to identify a unique identifier (e.g. key). If the variable specified contain
characters such as "/","\" or ":", they will be removed in the file name.

by(varlist) creates folders and sub-folders using the variables and order specified. The maximum number of variables allowed in by is 3. If by is not specified,
all media files will be logged into the primary destination folder specified in to(). Note that if the by() variables cointains missing variables some of the media
files will be saved into a folder named 'Missing'. If the variables specified contain
characters such as "/","\" or ":", they will be removed when creating folders.

vars(varlist) specificies variables to be used in the media files naming. The command will rename the files according the specified order.
If two variables are specified in vars(), the media file name will be constructed in the following way: `id'_`var1'_`var2'.
The maximum number of variables allowed in vars is 3. If the variables specified contain
characters such as "/","\" or ":", they will be removed in the file name.

mediafolder(folder_path) specifies the folder path that contains the SurveyCTO media files. Note that SurveyCTO Sync will create a folder named media
in your Sync destination for exported data. Specify this folder with from() (e.g. from("C:/Users/username/Documents/SurveyCTO Sync/media"))

outputfolder(folder_path) specifies the main destination folder path. If by is specified, additional sub-folders will be created.

resolve(varname) specifies the variable to be used in resolving duplicates on id.
This is only required if the variable specified in id() is not a unique identifiquer, i.e., has duplicates.
A common variable to use in resolve() is key, the unique identifier generated by SurveyCTO. If resolve() is specified,
the media file name will be constructed in the following way: `id'_`key'_`var1'. If the variable specified contain
characters such as "/","\" or ":", they will be removed in the file name.

Examples

All Examples will use the following locals as folder paths:

. local source "C:/Users/username/Documents/SurveyCTO Sync/media"

. local destination "C:/Users/username/Documents"

Example 1

sctomedia audio_audit, id(hhid) vars(district village) by(enumeratorid) media(`source') output(`destination')

In this example, sctomedia command is being run to rename and organize the media files stored in the variable 'audio_audit', which is an audio audit field. This dataset is related to a
household survey, where 'hhid' is the unique identifier of the households, 'enumeratorid' stores the unique identifier of the enumerator, and 'district' and 'village'
store the district and village of the household, respectively. This code will trigger the following actions:

. In `source', copy all media files matching the names stored in 'audio_audit'

. Inside `destination', create one folder for each enumeratorid and store the media files accordingly

. Renames all media files according to the sequence: `hhid'_`district'_`village'

Example 2

sctomedia image, id(hhid) vars(headname) media(`source') output(`destination') resolve(key)

In this example, sctomedia command is being run to rename and organize the media files stored in the variable 'image', which is an image field. This dataset is related to a
household survey, where 'hhid' is the unique identifier of the households and 'headname' is the name of the household head. Unfortunately, it was found that 'hhid' has duplicates, so resolve() is required
to be able to distinguish these duplicate observations. This code will trigger the following actions:

. In `source', copy all media files matching the names stored in 'image'

. Store these media files in `destination'

. Renames all media files according to the sequence: `hhid'_`key'_`headname' for duplicate observations, and `hhid'_`headname' for non-duplicate observations

Author

This command is the SurveyCTO version of a pre-existing resource for Stata users created by Innovations for Poverty Action (IPA). Both resources achieve the same aims
but this version has been tailored for more general use, compared to the specific requirements of IPA projects. You can see this command's
repository on Github.