{smcl}
{* 26 Aug 2019}{...}
{hline}
help for {hi:sctomedia}
{hline}

{title:Title}

{p 8 15 2}
{bf:sctomedia} {hline 2} rename and organize SurveyCTO media files

{marker syntax}{...}
{title:Syntax}

{p 8 15 2}
{cmd:sctomedia} {it:{help varname}} {help if:[if]} {help in:[in]}, [{cmd:by}({it:varlist})] {cmd:id}({it:varname}) {cmd:vars}({it:varlist}) {cmdab:media:folder}({it:folder_path}) {cmdab:output:folder}({it:folder_path}) 
{cmdab:res:olve}{it:(varname)}

{pstd}
You may enclose {it:folder_path} in double quotes.


{synoptset 25}{...}
{synopthdr}
{synoptline}
{synopt :{opt id(varname)}} Specifies the ID variable.{p_end}
{synopt :{opt by(varlist)}} Specifies the variables to be used to create folders, up to three levels.{cmd: [{it:optional}]}{p_end}
{synopt :{opt vars(varlist)}} Specifies the variables to be included in the new media filename.{p_end}
{synopt :{opt media:folder(folder_path)}} Source folder of media files.{p_end}
{synopt :{opt output:folder(folder_path)}} Destination folder of media files.{p_end}
{synopt :{opt res:olve(varname)}} Indicates a second ID variable.{cmd: [{it:required when id(varname) has duplicates}]}{p_end}
{synoptline}
{p2colreset}{...}


{marker description}{...}
{title:Description}

{pstd}
{cmd: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.

{pstd}
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.

{marker options}{...}
{title:Options}

{phang}
{opt 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.


{phang}
{opt 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.


{phang}
{opt 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.


{phang}
{opt media:folder(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"))


{phang}
{opt output:folder(folder_path)} specifies the main destination folder path. If by is specified, additional sub-folders will be created.


{phang}
{opt res:olve(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.


{marker examples}{...}
{title:Examples}

{pstd}All Examples will use the following locals as folder paths:{p_end}
{phang2}{cmd:. local} source "C:/Users/username/Documents/SurveyCTO Sync/media"{p_end}
{phang2}{cmd:. local} destination "C:/Users/username/Documents"{p_end}

   {hline}
{pstd}{cmd: Example 1}{p_end}

{pstd}{cmd:sctomedia} audio_audit, id(hhid) vars(district village) by(enumeratorid) media(`source') output(`destination')

{pstd}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:{p_end}
{phang2}{cmd:.} In `source', copy all media files matching the names stored in 'audio_audit'{p_end}
{phang2}{cmd:.} Inside `destination', create one folder for each enumeratorid and store the media files accordingly{p_end}
{phang2}{cmd:.} Renames all media files according to the sequence: `hhid'_`district'_`village'{p_end}

   {hline}
{pstd}{cmd: Example 2}{p_end}

{pstd}{cmd:sctomedia} image, id(hhid) vars(headname) media(`source') output(`destination') resolve(key)

{pstd}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:{p_end}
{phang2}{cmd:.} In `source', copy all media files matching the names stored in 'image'{p_end}
{phang2}{cmd:.} Store these media files in `destination'{p_end}
{phang2}{cmd:.} Renames all media files according to the sequence: `hhid'_`key'_`headname' for duplicate observations, and `hhid'_`headname' for non-duplicate observations{p_end}

    {hline}
{marker author}{...}
{title:Author}

{phang}
This command is the {browse www.surveycto.com: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 {browse www.github.com/surveycto/stata-scto:Github}.{p_end}
{phang}