dotscience 0.5.0

安装

您可以通过以下三种方法之一获取DotScience Python库。

使用Dotscience Jupyterlab环境

如果通过DotScience Web界面在Jupyter笔记本中使用DotScience，则已经安装了Python库（它安装在运行程序中正在执行的容器中）。在这种情况下，无需安装任何东西：只需在笔记本中将dotscience导入为ds即可。

如果使用DotScience跟踪源代码不是Jupyter笔记本的脚本的模型，请使用以下安装方法之一：

使用现成的Docker图像

我们制作了一个Docker镜像，方法是对python:3进行盘点，并像这样预先安装DotScience库：

$ docker run -ti quay.io/dotmesh/dotscience-python3:latest
Python 3.7.0 (default, Aug  4 2018, 02:33:39) 
[GCC 6.3.0 20170516] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import dotscience as ds

从pypi安装

$ pip install dotscience
Collecting dotscience
  Downloading https://files.pythonhosted.org/packages/b2/e9/81db25b03e4c2b0115a7cd9078f0811b709a159493bb1b30e96f0906e1a1/dotscience-0.0.1-py3-none-any.whl
Installing collected packages: dotscience
Successfully installed dotscience-0.0.1
$ python
Python 3.7.0 (default, Sep  5 2018, 03:25:31) 
[GCC 6.3.0 20170516] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import dotscience as ds

快速启动

最基本的用法是记录您读写的数据文件，并可能声明一些有关工作进展情况的摘要统计信息。

importdotscienceasdsimportpandasaspdds.interactive()ds.start()# Wrap the names of files you read with ds.input() - it just returns the filename:df=pd.read_csv(ds.input('input_file.csv'))# Likewise with files you write to:df.to_csv(ds.output('output_file.csv'))# Record a summary statistic about how well your job wentds.add_summary('f-score',f_score)ds.publish('Did some awesome data science!')

如果您使用jupyter，不要忘记在顶部调用ds.interactive（）和ds.start（），在最后调用ds.publish（），否则您的结果将不会被发布！（传入的运行描述字符串是可选的，因此如果您想不出什么好说的话，请将其删除）。

交互式与脚本模式

这个库有两种模式-交互和脚本。在上面的例子中，对ds.interactive（）的调用使它处于交互模式，这告诉它没有代码来自的脚本文件。但是，当您在python脚本文件中编写代码时，应该改为调用ds.script（）。

这将指示库在输出运行中记录脚本文件名（从sys.argv[0]），以便可以跟踪到原始脚本。在交互模式下不需要这样做，因为dotscience知道您使用的是哪一个jupyter笔记本-并且在这种情况下，sys.argv[0]指向jupyter python内核，在运行时记录它是没有用的！

如果sys.argv[0]在其他情况下没有帮助，可以调用ds.script（'filename'）来指定相对于当前工作目录的脚本文件。事实上，在jupyter笔记本中，您可以指定ds.script（'my-notebook.ipynb'）手动指定笔记本文件并覆盖笔记本文件的自动记录，但没有任何意义！

如果不调用ds.interactive（）或ds.script（），库将尝试通过检查其环境进行猜测。这在大多数情况下都应该有效，除非您从jupyterlab内部调用一个脚本（通过终端，或者通过调用笔记本中的system（）或类似的脚本），这时它会认为它处于交互模式-因此最好在脚本中包含ds.script（），jus以防万一！

您可以录制的所有内容

DotScience将为您跟踪的不仅仅是数据文件和摘要统计数据，还有多种方便的方法来指定每一项内容，这样它就可以很好地适应您的代码。下面是完整的列表：

开始和结束时间

库将尝试猜测作业的开始和结束时间，从调用start（）到调用publish（）（尽管在多次运行时会变得更复杂，请参见下文）。

如果你在Jupyter跑步，这意味着它将包括你花在笔记本上的时间，思考，等等，以及实际花在跑步骤上的时间，这可能不是你想要的。为了更好地跟踪运行时间，跟踪哪些操作比较慢，并将时间段与在同一台计算机上运行的其他内容交叉引用，以查看工作负载是否有干扰，最好在步骤开始时显式地告诉dotscience，停下来，

即使在通过ds run运行python脚本时，声明开始时间和结束时间仍然有帮助-如果脚本执行了大量繁琐的设置和拆卸，则可能不希望运行时包含这些时间。

只要在实际工作前后调用start（）和end（），库就会记录调用这些函数的当前时间。如果您错过了end（）函数，当您调用publish（）时，它将假定您的跑步已经完成；这通常是一个很好的假设，因此您通常可以在开始时调用start（），在结束时调用publish（），然后完成它。

importdotscienceasdsds.script()...setupcode...ds.start()...therealwork...ds.end()...cleanupcode...ds.publish('Did some awesome data science!')

或：

importdotscienceasdsds.script()...setupcode...ds.start()...therealwork...ds.publish('Did some awesome data science!')

DotScience仍然会记录工作负载实际执行的开始和结束时间（这是命令工作负载的整个脚本，或者是jupyter工作负载的保存间隔时间），但这是单独保存的。

错误

有时候，跑步失败了，但你还是想记录下它的发生（也许这样你就知道不要再做同样的事情了…）。您可以将运行声明为失败，如下所示：

importdotscienceasdsds.script()ds.start()...ds.set_error('The data wasn'tcorrectlyformatted')...ds.publish('Tried, in vain, to do some awesome data science!')

如果您将错误消息组装为用于其他原因，则DotScience库可以在使用之前获取它的副本，并使用此方便的函数返回其参数：

importdotscienceasdsds.script()ds.start()...raiseDataFormatError(ds.error('The data wasn'tcorrectlyformatted'))...ds.publish('Tried, in vain, to do some awesome data science!')

描述运行

很好的方法是记录一个人类可读性很强的关于你跑步所做的事情的描述，这有助于人们查看出处图。我们已经了解了如何将描述传递到publish（）：

importdotscienceasdsds.script()ds.start()ds.publish('Did some awesome data science!')

但您可以在此之前设置描述，只需调用publish（）而无需参数：

importdotscienceasdsds.script()ds.start()...ds.set_description('Did some awesome data science!')...ds.publish()

如果您已经创建了一个描述性字符串发送到其他地方，也可以使用此函数，该函数返回其参数：

$ docker run -ti quay.io/dotmesh/dotscience-python3:latest
Python 3.7.0 (default, Aug  4 2018, 02:33:39) 
[GCC 6.3.0 20170516] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import dotscience as ds

如果您愿意，您还可以将描述传递给start（），尽管使用过去时进行您将要执行的操作可能会感到奇怪：

$ docker run -ti quay.io/dotmesh/dotscience-python3:latest
Python 3.7.0 (default, Aug  4 2018, 02:33:39) 
[GCC 6.3.0 20170516] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import dotscience as ds

输入和输出文件

为了正确跟踪数据文件的来源，DotScience需要您正确声明作业读写的数据文件。

最方便的方法是使用input（）和output（），它们分别接受要用于输入或输出的文件名，并返回：

$ docker run -ti quay.io/dotmesh/dotscience-python3:latest
Python 3.7.0 (default, Aug  4 2018, 02:33:39) 
[GCC 6.3.0 20170516] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import dotscience as ds

但是您也可以使用add_input（）和add_output（）显式声明它们：

$ docker run -ti quay.io/dotmesh/dotscience-python3:latest
Python 3.7.0 (default, Aug  4 2018, 02:33:39) 
[GCC 6.3.0 20170516] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import dotscience as ds

或者使用add_inputs（）和add_outputs（）同时声明多个

$ docker run -ti quay.io/dotmesh/dotscience-python3:latest
Python 3.7.0 (default, Aug  4 2018, 02:33:39) 
[GCC 6.3.0 20170516] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import dotscience as ds

您还可以将目录命名为输入和输出。

如果将目录作为输入，则在调用ds.input（），ds.add撸input（）或ds.add撸inputs（）时，将扫描该目录，并将该目录（或其子目录）中的所有文件记录为输入；出现的任何新文件稍后将不包括在内，因为假定您会在调用后立即读取这些文件，因此任何随后添加的文件都是稍后处理步骤的结果。

对于标记为输出的目录，只有在发布运行时才会扫描该目录。这是因为您最喜欢在空目录上调用ds.output（）或类似的方法，然后后续步骤将用文件填充该目录。存储目录名，当运行发布时，将扫描该目录（及其所有子目录）以查找要记录为输出的文件。

请注意，在这两种情况下，相对路径名都是相对于当前工作目录进行解释的；库将根据运行元数据格式的要求，将它们转换为相对于工作区根目录的路径。

标签

您可以将任意标签附加到您的运行中，该标签可用于在DotScience用户界面中搜索它们。像往常一样，这可以在le使用label（）返回标签值，显式使用add_label（）返回标签值，或使用add_labels（）返回批量值：

$ docker run -ti quay.io/dotmesh/dotscience-python3:latest
Python 3.7.0 (default, Aug  4 2018, 02:33:39) 
[GCC 6.3.0 20170516] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import dotscience as ds

汇总统计

通常情况下，您的工作将能够以某种方式衡量自己的性能—也许可以测试在某些训练数据上训练的模型在某些测试数据上的工作情况。如果您向DotScience声明这些摘要统计数据，它可以帮助您跟踪哪些运行产生了最佳结果。

像往常一样，这可以在返回摘要值时使用summary（），显式使用add廑summary（）或大量使用add廑summaries（）：

$ docker run -ti quay.io/dotmesh/dotscience-python3:latest
Python 3.7.0 (default, Aug  4 2018, 02:33:39) 
[GCC 6.3.0 20170516] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import dotscience as ds

参数

通常，数据科学家的工作包括运行相同的算法，同时调整一些输入参数，以查看哪些设置最有效。如果您向dotscience声明输入参数，它可以跟踪它们并帮助您找到最好的参数！

通常，这可以在使用parameter（）返回参数值时完成，使用add\u parameter（）显式返回参数值，或使用add\u parameters（）返回参数值时完成：

$ docker run -ti quay.io/dotmesh/dotscience-python3:latest
Python 3.7.0 (default, Aug  4 2018, 02:33:39) 
[GCC 6.3.0 20170516] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import dotscience as ds

$ docker run -ti quay.io/dotmesh/dotscience-python3:latest
Python 3.7.0 (default, Aug  4 2018, 02:33:39) 
[GCC 6.3.0 20170516] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import dotscience as ds

$ docker run -ti quay.io/dotmesh/dotscience-python3:latest
Python 3.7.0 (default, Aug  4 2018, 02:33:39) 
[GCC 6.3.0 20170516] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import dotscience as ds

$ pip install dotscience
Collecting dotscience
  Downloading https://files.pythonhosted.org/packages/b2/e9/81db25b03e4c2b0115a7cd9078f0811b709a159493bb1b30e96f0906e1a1/dotscience-0.0.1-py3-none-any.whl
Installing collected packages: dotscience
Successfully installed dotscience-0.0.1
$ python
Python 3.7.0 (default, Sep  5 2018, 03:25:31) 
[GCC 6.3.0 20170516] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import dotscience as ds