This reduces the boilerplate for automatically creating command line scripts with python. Probably other projects like this exist, but this one is small. Right now we only support google style of documentation, which is compatible with using Spinx with its extension: the Napoleon module.
Consider this function with a long long description:
def apex3d(raw_folder,
output_dir,
lock_mass_z2=785.8426,
lock_mass_tol_amu=.25,
low_energy_thr=300,
high_energy_thr=30,
lowest_intensity_thr=750,
write_xml=True,
write_binary=True,
write_csv=False,
max_used_cores=1,
path_to_apex3d='C:/SYMPHONY_VODKAS/plgs/Apex3D64.exe',
PLGS=True,
cuda=True,
unsupported_gpu=True,
debug=False,
**kwds):
"""A wrapper around the infamous Apex3D.
It wraps in Python what would otherwise had to be called with a batch script.
Args:
raw_folder (str): a path to the input folder with raw Waters data.
output_dir (str): Path to where to place the output.
lock_mass_z2 (float): The lock mass for doubly charged ion (which one, dunno, but I guess a very important one).
lock_mass_tol_amu (float): Tolerance around lock mass (in atomic mass units, amu).
low_energy_thr (int): The minimal intensity of a precursor ion so that it ain't a noise peak.
high_energy_thr (int): The minimal intensity of a fragment ion so that it ain't a noise peak.
lowest_intensity_thr (int): The minimal intensity of a peak to be analyzed.
write_xml (boolean): Write the output in an xml in the output folder.
write_binary (boolean): Write the binary output in an xml in the output folder.
write_csv (boolean): Write the output in a csv in the output folder (doesn't work).
max_used_cores (int): The maximal number of cores to use.
path_to_apex3d (str): Path to the "Apex3D.exe" executable.
PLGS (boolean): No idea what it is.
cuda (boolean): Use CUDA.
unsupported_gpu (boolean): Try using an unsupported GPU for calculations. If it doesn't work, the pipeline switches to CPU which is usually much slower.
debug (boolean): Debug mode.
kwds: other parameters for 'subprocess.run'.
Returns:
tuple: the path to the outcome (no extension: choose it yourself and believe more in capitalism) and the completed process.
"""
pass
Our module helps to automatically parse the function signature and documentation and make it ready to be used with the argparse
module.
Look:
from docstr2argparse import foo2argparse
pprint(foo2argparse(apex3d))
gives:
In [197]: pprint(foo2argparse(apex3d))
('Analyze a Waters Raw Folder with Apex3D.',
[('--PLGS', {'default': True, 'help': 'No idea what it is. [default: True].'}),
('--cuda', {'default': True, 'help': 'Use CUDA. [default: True].'}),
('--high_energy_thr',
{'default': 30,
'help': "The minimal intensity of a fragment ion so that it ain't a noise "
'peak. [default: 30].',
'type': <class 'int'>}),
('--lock_mass_tol_amu',
{'default': 0.25,
'help': 'Tolerance around lock mass (in atomic mass units, amu). [default: '
'0.25].',
'type': <class 'float'>}),
('--lock_mass_z2',
{'default': 785.8426,
'help': 'The lock mass for doubly charged ion. [default: 785.8426].',
'type': <class 'float'>}),
('--low_energy_thr',
{'default': 300,
'help': "The minimal intensity of a precursor ion so that it ain't a noise "
'peak. [default: 300].',
'type': <class 'int'>}),
('--lowest_intensity_thr',
{'default': 750,
'help': 'The minimal intensity of a peak to be analyzed. [default: 750].',
'type': <class 'int'>}),
('--max_used_cores',
{'default': 8,
'help': 'The maximal number of cores to use. [default: 8].',
'type': <class 'int'>}),
('output_dir',
{'help': 'Path to where to place the output.', 'type': <class 'str'>}),
('--path_to_apex3d',
{'default': 'C:/SYMPHONY_VODKAS/plgs/Apex3D64.exe',
'help': 'Path to the "Apex3D.exe" executable. [default: '
'C:/SYMPHONY_VODKAS/plgs/Apex3D64.exe].',
'type': <class 'str'>}),
('raw_folder',
{'help': 'a path to the input folder with raw Waters data.',
'type': <class 'str'>}),
('--timeout_apex3d',
{'default': 60,
'help': 'Timeout in minutes. [default: 60].',
'type': <class 'float'>}),
('--unsupported_gpu',
{'default': True,
'help': "Try using an unsupported GPU for calculations. If it doesn't "
'work, the pipeline switches to CPU which is usually much slower. '
'[default: True].'}),
('--write_binary',
{'default': True,
'help': 'Write the binary output in an xml in the output folder. [default: '
'True].'}),
('--write_csv',
{'default': False,
'help': "Write the output in a csv in the output folder (doesn't work). "
'[default: False].'}),
('--write_xml',
{'default': False,
'help': 'Write the output in an xml in the output folder. [default: '
'False].'})])
Neet. But that's not all folks.
from docstr2argparse import document
document(apex3d).print_help()
generates the almighty help:
usage: ipython3 [-h] [--PLGS PLGS] [--cuda CUDA]
[--high_energy_thr HIGH_ENERGY_THR]
[--lock_mass_tol_amu LOCK_MASS_TOL_AMU]
[--lock_mass_z2 LOCK_MASS_Z2]
[--low_energy_thr LOW_ENERGY_THR]
[--lowest_intensity_thr LOWEST_INTENSITY_THR]
[--max_used_cores MAX_USED_CORES]
[--path_to_apex3d PATH_TO_APEX3D]
[--timeout_apex3d TIMEOUT_APEX3D]
[--unsupported_gpu UNSUPPORTED_GPU]
[--write_binary WRITE_BINARY] [--write_csv WRITE_CSV]
[--write_xml WRITE_XML]
output_dir raw_folder
Analyze a Waters Raw Folder with Apex3D.
positional arguments:
output_dir Path to where to place the output.
raw_folder a path to the input folder with raw Waters data.
optional arguments:
-h, --help show this help message and exit
--PLGS PLGS No idea what it is. [default: True].
--cuda CUDA Use CUDA. [default: True].
--high_energy_thr HIGH_ENERGY_THR
The minimal intensity of a fragment ion so that it
ain't a noise peak. [default: 30].
--lock_mass_tol_amu LOCK_MASS_TOL_AMU
Tolerance around lock mass (in atomic mass units,
amu). [default: 0.25].
--lock_mass_z2 LOCK_MASS_Z2
The lock mass for doubly charged ion. [default:
785.8426].
--low_energy_thr LOW_ENERGY_THR
The minimal intensity of a precursor ion so that it
ain't a noise peak. [default: 300].
--lowest_intensity_thr LOWEST_INTENSITY_THR
The minimal intensity of a peak to be analyzed.
[default: 750].
--max_used_cores MAX_USED_CORES
The maximal number of cores to use. [default: 8].
--path_to_apex3d PATH_TO_APEX3D
Path to the "Apex3D.exe" executable. [default:
C:/SYMPHONY_VODKAS/plgs/Apex3D64.exe].
--timeout_apex3d TIMEOUT_APEX3D
Timeout in minutes. [default: 60].
--unsupported_gpu UNSUPPORTED_GPU
Try using an unsupported GPU for calculations. If it
doesn't work, the pipeline switches to CPU which is
usually much slower. [default: True].
--write_binary WRITE_BINARY
Write the binary output in an xml in the output
folder. [default: True].
--write_csv WRITE_CSV
Write the output in a csv in the output folder
(doesn't work). [default: False].
--write_xml WRITE_XML
Write the output in an xml in the output folder.
[default: False].
It should work under both Pythons, but use Python3 just to make Michał Startek feel old and useless.
pip3 install docstr2argparse